Payment links

A payment link opens the checkout for a specific charge. The customer, title, description, amount and due date come from that charge. The link lets you configure destinations for returning to your website and restrict the payment methods offered to the payer.

Integration requests use https://api.raims.com.

These five requests manage payment links:

Link to the charge

Create the charge before requesting its link and store the identifier returned by the API. In Create a payment link, send this identifier in charge_id. The charge must belong to the company and environment of your API key.

charge_id uses the charge identifier, with the ch_ prefix. The link's id uses pl_; it identifies the link in lookups, updates and email requests.

The link does not create another customer or charge. It does not define its own price, due date or financial status. To check this data, use Retrieve a charge with the charge_id.

Create or retrieve the link

POST /v1/payment_links creates the link for an existing charge or reuses the link it already has. The response includes the link's id, charge_id and url for opening the checkout, along with the link settings. To create or configure the link, the charge must be open and within its due date.

To receive the link when creating the charge, use create_checkout: true in Create a new charge. This option avoids a separate request to obtain the URL without requiring an email request or return URL.

Creating or retrieving the link does not confirm payment or request an email. While the charge allows this action, repeating the request does not create another link. A new link starts active. If the existing link is paused, POST keeps it paused. Use PATCH to reactivate it.

Configure the link

You can send success_redirect_url, cancel_redirect_url and payment_method_types in POST /v1/payment_links when creating the link, or use PATCH /v1/payment_links/{id}, described in Update a payment link, afterward.

After configuring the link, call GET /v1/payment_links/{id} and check is_payable. The is_active field and effective_payment_method_types list may still be populated even when the checkout cannot accept payment. The list shows the methods defined by the settings; is_payable indicates whether payment is still possible at that moment.

success_redirect_url sets the return destination after payment is confirmed, under the conditions in Guide someone who received a link. cancel_redirect_url sets the address for the option to return to the company's website. This navigation does not cancel the charge, Pix or boleto.

Send complete, valid HTTPS URLs. Omitting a URL, sending null, empty text or only spaces keeps the registered address. In a new link without an address, the corresponding return option has no destination.

To remove a registered destination, use PATCH with clear_success_redirect_url: true or clear_cancel_redirect_url: true. You can send both commands to remove both destinations. Sending false or omitting the command does not request removal. These commands are only for updating a link; they are not sent when creating a charge or link and do not appear in the response.

After removal, the corresponding URL returns null. Without a success destination, checkout does not redirect automatically; without a cancellation destination, the option to return to the website has no address. Removing a destination does not cancel the charge, Pix or boleto. The update requires an open charge within its due date, even when only removing a destination.

A populated URL and its clearing command set to true are incompatible in the same request. The API returns HTTP 400 with INVALID_FIELDS and MUTUALLY_EXCLUSIVE details for both fields. Choose whether to set or remove that destination. You can remove one destination and change the other.

payment_method_types lets you restrict the methods accepted by the link. Omitting the field keeps the existing configuration. Sending null removes the link's custom configuration and returns to the charge and account checkout settings. A populated list must respect the methods accepted by the charge and available on the platform. See the codes in Payment methods.

Changing the link's configuration does not change the customer, title, amount, due date or charge status. Use the Charges requests to look up data and make changes allowed for that resource.

You can also pause the checkout with is_active: false and reactivate it with is_active: true in PATCH. For the payer, a paused link without a confirmed payment appears as not found or unavailable without revealing the pause. See Pause and reactivate for the conditions and effects of this setting.

Pause and reactivate

Use Update a payment link with PATCH /v1/payment_links/{id} and is_active: false to pause the checkout. To reactivate it, send is_active: true to the same endpoint. Omitting this field keeps the current state; null, numbers and text are invalid.

{
  "is_active": false
}

Pausing keeps the same identifier and URL. The checkout blocks new payment actions and new email or resend requests while paused. Email requests and payments accepted before the pause can continue normally. You can change its other settings without reactivating it. The charge must be open and within its due date to pause, reactivate or configure the link.

After the charge expires, PATCH cannot reactivate its link. Pausing or reactivating keeps the same id and url; neither action extends the charge's due date.

When opening the URL of a paused link without a confirmed payment, the payer receives the same not-found or unavailable message. The page does not reveal the pause. This message alone does not identify the reason; the payer should check the received address and contact the company that issued the charge. The company can check is_active through the authenticated API to verify the setting. Receipts for confirmed payments remain accessible.

The due date continues to approach while the link is paused. Pix and boleto already issued are not canceled and may still be paid outside checkout. To cancel the charge, use Revoke a charge and track confirmation. Pausing the link does not replace revocation.

Create, list, lookup and update responses include is_active. A true value means the link is not paused, but does not guarantee that the charge can accept payment. Check is_payable in the individual GET before offering checkout. Repeating the current configuration keeps the same link.

Look up and share

Use GET /v1/payment_links, described in List payment links, to browse the account's links. The charge_id filter selects links associated with the specified charge. Keep this filter when moving between pages.

Use GET /v1/payment_links/{id}, described in Retrieve a payment link, with the link's id to check its URL, configuration and current availability. Link and charge identifiers serve different purposes; use each in the indicated field.

In the individual GET, is_payable indicates whether the charge can still be paid through the link. When it is paid, revoked or expired, the link remains available for lookup but does not allow a new payment. Other situations, such as a boleto awaiting confirmation, may also prevent a new payment.

payment_method_types shows the link's custom configuration, or null to use the charge and account configuration. In this lookup, the list is empty if the configuration contains neither Pix nor boleto; this does not allow sending an empty list when creating or updating the link. effective_payment_method_types shows the methods defined by the charge, link and account settings among those available on the platform. A paid charge or paused link may still show Pix and boleto in this list. Use is_payable to check whether checkout can still accept payment.

When is_payable is false, unavailable_reason shows the reason. Use unavailable_reason.code in your integration; message is an English diagnostic explanation whose text may change. When the charge can be paid through the link, unavailable_reason is null.

When the reason is the charge state, the message shows the current state and the accepted states. If an open charge is past its due date, it also shows due_date in Unix UTC seconds. The same explanation appears when this condition prevents configuring the link or requesting an email.

Availability follows the charge's checkout rules and may change after the lookup. These fields do not confirm payment or reserve a method. The lookup does not issue Pix or boleto or extend the due date. Creation, listing and updates continue to return the link's configuration; use the individual GET to check availability.

Share the url returned by the API. Do not build the address from the id. Lookups use the existing link and do not generate another checkout.

Send by email

To send or resend an existing payment link through the API, use POST /v1/payment_links/{id}/send_email, described in Email a payment link. Provide the id in the path, with no request body. The link must be active and the charge must be open and within its due date. A paused link returns HTTP 409 with PAYMENT_LINK_PAUSED; reactivate it before requesting the email. The request does not create another link, change the checkout or issue Pix or boleto.

The recipient is the payer's email registered on the boleto, when present. Otherwise, it uses the email registered on the charge and, if that is also missing, the email in the customer's current record. An invalid address prevents sending. This request does not allow another recipient. While the company's registration is pending, sending is restricted to the account holder's email.

After a request is accepted by this endpoint, wait 60 seconds before requesting another email for the same charge. This interval is shared with the Dashboard's resend action and all other keys and servers for the same company. If you receive HTTP 429, wait for the Retry-After interval before trying again through the API or Dashboard. The success response shows the recipient in recipient_email and the resend interval in retry_after_seconds and retry_after_until, the latter in Unix UTC seconds.

HTTP 202 confirms that the email request was registered. It does not prove inbox delivery or that the recipient read it. To track payment, look up the linked charge.

Sandbox can also send real emails. When testing this endpoint, use a test address you control.

Track payment

Look up the charge identified by charge_id to track its status and obtain available Pix or boleto data. Opening the link, issuing a payment method or returning to the website does not confirm that the charge was paid.

The link follows the linked charge's conditions. Checkout expiration does not confirm cancellation of a boleto already issued. To cancel an eligible charge, use Revoke a charge and track confirmation; editing the link does not replace this action.

Environment and access

Link management uses https://api.raims.com and requires an API key. The company and environment come from the key. Sandbox links and charges are kept separate from Production data. Use Sandbox to test without moving real funds.

Anyone who receives the URL can open checkout. Do not share your API key with the payer or include it in the URL. The public address does not allow managing the link or charge settings.