Skip to main content

​
Overview

Tesouro provides an embeddable Payment component that allows our partners to build a custom invoice payment and BillPay experience into their applications or websites. The Payment component is an alternative to hosted payment pages, and allows users (organizations or their counterparts) to make payments without leaving your application. From an integration perspective, using the Payment component requires:
  • Server side: to generate a payment link ID, receive webhooks about the payment status, and (optionally) customize the look and feel of the Payment component.
  • Client side: the Payment component handles all necessary payment-related requests and validates the inputs.
Tesouro Payment component

​
Payment methods

The payment methods displayed by the component are configured when you generate a payment link ID for this component, as explained below. Additionally, the organization that will receive or make the payment:

​
Usage

Embedding the Payment component into your web page requires just two lines of code. First, import the Payment component’s module: 
{/** Production only **/}
<script type="module" src="https://pay.tesouro.com/drop-in/index.js"></script>

{/** Sandbox only **/}
<script type="module" src="https://pay.sandbox.tesouro.com/drop-in/index.js"></script>
Then initialize the Payment component: 
<tesouro-payment link-id="PAYMENT_LINK_ID" />

The PAYMENT_LINK_ID must be generated in advance by calling POST /payment-links with your partner access token. Payment links can be created for Accounts Payable invoices (organization pays), Accounts Receivable invoices (organization gets paid), or arbitrary monetary amounts (organization pays or gets paid). For more information, see Payment links. In the body of the POST /payment-links request, specify the payment methods you want to display in the component (assuming these methods are already enabled for the organization). The following example creates a payment link ID for an external invoice that an organization issued to its counterpart. The counterpart is supposed to use your payment page to make the payment to the organization. 
curl -X POST 'https://api.sandbox.tesouro.com/v1/payment-links' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "payment_methods": [
         "card"
       ],
       "recipient": {
         "id": "e575bbe2-38ef-48a4-b21a-b72801bd9d17",
         "type": "entity"
       },
       "return_url": "https://return.url.com",
       "amount": 1250,
       "currency": "USD",
       "payment_reference": "Inv 102",
       "invoice": {
         "issue_date": "2024-04-18",
         "due_date": "2024-05-18"
       }
     }'
The response from POST /payment-links contains a unique id. This is the ID you need to pass to the Tesouro Payment component via the <tesouro-payment link-id="PAYMENT_LINK_ID" /> tag on your payment page. 
{
  "id": "8a3b5037-ae70-42c3-8cf1-c10b44e07a8c",
  "amount": 1250,
  "currency": "USD",
  ...
}

​
Customization

The look and feel of the payment component can be customized to match your branding. The colors and other styling options are controlled by the partner setting payments.payment_page_theme, which you can change by calling PATCH /settings. For details, see Payment page customization.