Overview

Call the Payouts API to request host-to-host payout methods.

The API parameters are organized into distinct objects to streamline the payout process and ensure clarity in data handling. Each object represents a specific aspect of the transaction, making it easier to manage and understand the flow of information. However, some parameters stand alone and are not part of any object. Below is an overview of the objects and their corresponding parameters, as well as the standalone parameters:

• Customer: Represents the individual making the payout. This object includes critical information about the customer, such as their unique ID, name, email address, and optionally, their IP address and birthdate. The customer.document sub-object details the type and number of the customer's official identification, while the customer.address sub-object includes the customer's full address, which may be required depending on the payout method.

• Transaction: This object contains all the essential details about the transaction itself, including a unique transaction ID, the currency used, the total amount involved, and optionally, the time until the transaction expires.

• Payment: Represents the payout method and related URLs for completing the transaction. This object is crucial for determining how the customer will pay and where they will be redirected after the payout is completed.

• Values: This object provides detailed financial information related to the transaction. It includes the original and converted amounts, the currencies involved, the exchange rate applied, and any fees associated with the transaction.

Standalone parameters, such as branch, country, notification_url, and redirect_url, do not belong to any specific object. These parameters provide additional information relevant to the transaction, such as the location of the transaction, the country code, where payout notifications should be sent, and where the customer should be redirected after completing the payout.

Our API structure remains consistent across different payout methods and countries, making it easy to adapt as you expand into new regions or integrate new methods.

Knowing the parameters used

Parameter	Type	Description
customer.id	string	Unique identifier for the customer in your system. This value should remain consistent across all transactions for the same customer
customer.name	string	The full name of the customer making the payout. It should match the name on the customer's identification documents
customer.email	string	The email address of the customer. This will be used for sending payout confirmations and notifications
customer.phone	string	The phone number of the customer, including the country code. This parameter may be optional or required depending on the payout method used
customer.birthdate	string	The birthdate of the customer, provided in the format mm-dd-yyyy. This parameter may be required depending on the country regulations or the payout method
customer.document.number	string	The official identification number of the customer. This is typically a national ID, passport, or other government-issued document
customer.document.type	string	The type of document provided by the customer. Common types include national ID, passport, or driver's license. List of documents allowed.
customer.address.addres_1	string	The primary street address of the customer
customer.address.addres_2	string	Additional address information, such as apartment number or suite
customer.address.city	string	The city in which the customer resides
customer.address.country_code	string	The ISO 3166-1 alpha-3 country code for the customer's address. List of country codes.
customer.address.neightborhood	string	The neighborhood or district of the customer's address
customer.address.number	string	The street number of the address
customer.address.postal_code	string	The postal or ZIP code for the customer's address
customer.address.state	string	The state or region of the customer's address
transaction.id	string	A unique identifier for the transaction. This ID should be generated by your system to track the specific payout process
transaction.currency	string	The currency in which the transaction is being conducted. Use standard ISO 4217 currency codes (e.g., USD, PEN). List of currency codes.
transaction.amount	decimal (10,2)	The total amount of the transaction in the specified currency. This value should be a numeric amount (use dot instead of comma) Eg: 300.10
branch	string	The specific branch or location identifier where the transaction is being processed, if applicable
country	string	The country code where the transaction is taking place. The format is ISO 3166-1 alpha-3 (e.g., BRA for Brazil). List of country codes.
payment_method	string	The method of payment being used for the transaction, such as bank transfer, credit card...
notification_url	string	The URL to which payment notifications will be sent. Ensure this URL is accessible and configured to handle the notification format

Example response for a bank_transfer payout method request

success

{
    "requestId": "de3af972e3cea7d6cd998bc4761f05f4\/15349144900800090226",
    "data": {
	"id": "2d6c4f53-8ec4-4cfc-82b7-df1bde11bf92",
	"status": "pending",
	"payment": {
	    "method": "bank_transfer"
	},
	"values": {
	    "source_total": "18.00000000",
	    "source_currency": "PEN",
	    "exchanged_total": "18.00",
	    "exchanged_currency": "PEN",
	    "exchange": "1.00",
	    "fee": "0.18000000"
	}
    }
}

error

{
    "requestId": "b299549a8e75ead38c176932c3f59da0/13462186452875824120",
    "moreInformation": [
        {
            "code": "INVALID_REQUEST",
            "detail": "The transaction.id field is required."
        }
    ]
}

Response details

Parameter	Description
id	A unique identifier for the response generated by the payment system, used to track the transaction. Can be used to verify the payment status in the GET /payout/{id} endpoint
status	The current status of the transaction such as pending, onhold, success, refunded, failed
payment.method	The payment method that was used for the transaction, such as bank_transfer, pix...
values.source_total	The total amount of the transaction in the source currency before any exchange
values.source_currency	The original currency of the transaction as specified in the request
values.exchanged_total	The total amount of the transaction after currency conversion, if applicable
values.exchanged_currency	The currency in which the payment was completed after conversion
values.exchange	The exchange rate applied to convert the source currency to the target currency
values.fee	The amount charged by our service for processing the transaction

---

Our API is designed to be flexible and adaptable, so as you expand into new regions or add more payment methods, you can easily apply these principles across different implementations.

If you need further details on other payment methods or countries, be sure to explore the rest of our documentation. Additionally, we have a dedicated FAQ and support section to help with common questions:

FAQ & Support