Payouts API

This feature allows you to create multiple and secure payments for payees (users, merchants, providers, customers, etc.) using the funds you have in your PayU Account.

For introductory terms, how to request this service and more information, refer to Payouts.

Configuring the authentication

To use the methods to manage Payouts or WebHooks exposed by the Payouts service, you must include the Authorization and PublicKey headers:

To configure the Authorization header, call the authentication method provided by the Payouts service.
Example:

Bearer eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiQWRtaW4iLCJJc3N1ZXIiOiJJc3N1ZXIiLCJVc2VybmFtZSI6IkphdmFJblVzZSIsImV4cCI6MTYyODU0ODE2NywiaWF0IjoxNjI4NTQ4MTY3fQ.jrO3u5ramYKOvoNNb0TNfBuZkbYg1EvPmCDDYXFEO4c

To configure the PublicKey header, use your Public Key which can be found in the PayU Module (Settings > Technical configuration > Public Key).

PrintScreen

Available methods

Payouts API includes the following methods:

Authentication
Request payout
Cancel payout request
Create or update a WebHook
Delete a WebHook
Query WebHooks

Authentication

The first step regardless of the method you want to request is to authenticate your account using the credentials provided by PayU.

The authentication method logs in the merchant returning the JWT Token generated to use the services exposed by Payouts. This token is available during 10 minutes after its creation.

API Call

To authenticate, send the request as follows:

POST
https://{env-api}.payulatam.com/v1.0/authenticate?accountId={accountId}&apiKey={apiKey}&apiLogin={apiLogin}

The value for the variable {env-api} displayed above is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
accountId	ID of the user account for each country associated with the merchant.	Yes
apiKey	Password provided by PayU. How do I get my API Key	Yes
apiLogin	User or login provided by PayU. How do I get my API Login	Yes

Response example

{
  "token": "Bearer eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiQWRtaW4iLCJJc3N1ZXIiOiJJc3N1ZXIiLCJVc2VybmFtZSI6IkphdmFJblVzZSIsImV4cCI6MTYyODU0ODE2NywiaWF0IjoxNjI4NTQ4MTY3fQ.jrO3u5ramYKOvoNNb0TNfBuZkbYg1EvPmCDDYXFEO4c"
}

Request payout

This method lets you create one or multiple Payouts request for payees which can be new or existing. As soon as you create the request, this moves along the available states for Payouts.

Note

You need to include two headers to use this method, refer to Configuring authentication for more information. Furthermore, you need to know your Merchant and account ID, you can get this information in your PayU Module.

API Call

To create a Payout request, use the following URL:

POST
https://{env-api}.payulatam.com/v1.0/supplier-transfers/{merchantId}/{accountId}

The value for the variable {env-api} displayed above is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
merchantId	Merchant’s ID number in PayU’s system.	Yes
accountId	ID of the user account for each country associated with the merchant.	Yes

Both parameters can be found in your PayU module.

Variables for request and response

Request parameters

Show mandatory fields only

Field name	Format	Size	Description	Mandatory
transfers	List		List of the transfers you want to create.	Yes
transfers[n] > value	Numeric		Amount to be transfer from your funds. The currency of this amount is the one configured in your PayU account	Yes
transfers[n] > bankAccount			This object has the information of the bank account of the payee that will receive the payment. The payee can be existing or new.	Yes
transfers[n] > bankAccount > id	Alphanumeric	36	Identifier of the Bank account of the payee. Send this parameter when you want to request a Payout for an existing payee.	No
transfers[n] > bankAccount > supplierType	Alphanumeric	Min:11 Max:16	Relationship type between you and your payee. You can choose one of the following values: `SUBMERCHANT`: select this relation if the payee is a related merchant. `RELATED_PROVIDER`: select this relation if the payee is a provider `RELATED_THIRD_PARTY`: select this type if the payee is a customer, an employee, or any user of your services. This parameter is mandatory when you are creating a payout request for a new payee.	No
transfers[n] > bankAccount > accountNumber	Alphanumeric	Max:17	Bank account number of the payee. This parameter is mandatory when you are creating a payout request for a new payee.	No
transfers[n] > bankAccount > bankCode	Numeric	Min:3 Max:4	Code of the bank who issued the account of the payee. See Bank codes.	No
transfers[n] > bankAccount > accountType	Alphanumeric	2	Set `CC` for Current account and `CA` for Saving account or `Nequi`^. This parameter is mandatory when you are creating a payout request for a new payee. ^Nequi is available in Colombia.	No
transfers[n] > bankAccount > country	Alphanumeric	2	Country of the bank account in format ISO 3166 Alpha-2. This parameter is mandatory when you are creating a payout request for a new payee.	No
transfers[n] > bankAccount > documentNumber	Numeric	50	Identification number of the payee. If the `documentType` is `NIT`, the document number must have a hyphen (`-`) and the check digit. Example: `830140299-6`. This parameter is mandatory when you are creating a payout request for a new payee.	No
transfers[n] > bankAccount > documentType	Alphanumeric	2	Identification type of the payee. See Document types. This parameter is mandatory when you are creating a payout request for a new payee.	No
transfers[n] > bankAccount > expeditionDate	Alphanumeric	10	Expedition date of the identity document of the payee. Format `YYYY/MM/DD`.	No
transfers[n] > bankAccount > fullName	Alphanumeric		Full name of the payee. This parameter is mandatory when you are creating a payout request for a new payee.	No
transfers[n] > bankAccount > birthDate	Alphanumeric	10	Birth date of the payee. Format `YYYY/MM/DD`.	No
transfers[n] > bankAccount > state	Alphanumeric		State of the Bank account. Set `ACTIVE` when you are creating a new payee.	No
transfers[n] > bankAccount > merchantId	Numeric		Identifier of your commerce in PayU.	No
transfers[n] > description	Alphanumeric		Additional information of the payout.	No

Response parameters

Field name	Format	Size	Description
totalSuccessful	Numeric		Number of payouts successfully created.
totalFailed	Numeric		Number of payments that could not be created.
successfulItems	List		List of items that were successfully processed.
successfulItems[n] > processingStatus	Alphanumeric	7	Status of the Payout request. For successful transactions, the value is `SUCCESS`
successfulItems[n] > paymentOrderId	Alphanumeric	36	Id generated for the payout request. Use this id to cancel the request.
successfulItems[n] > value	Numeric		Amount of the request.
successfulItems[n] > bankAccount			This object has the information of the bank account that will receive the payment.
successfulItems[n] > bankAccount > processingStatus	Alphanumeric	7	Bank account registration status. For successful registrations, the value is `SUCCESS`.
successfulItems[n] > bankAccount > id	Alphanumeric	36	Identifier of the registered Bank account.
successfulItems[n] > bankAccount > supplierType	Alphanumeric	Min:11 Max:16	Relationship type selected for the payee.
successfulItems[n] > bankAccount > accountNumber	Alphanumeric	Max:17	Bank account number of the payee.
successfulItems[n] > bankAccount > bankCode	Numeric	Min:3 Max:4	Code of the bank who issued the account of the payee. See Bank codes.
successfulItems[n] > bankAccount > bankName	Alphanumeric		Bank name of the payee.
successfulItems[n] > bankAccount > accountType	Alphanumeric	2	Account type of the of the payee.
successfulItems[n] > bankAccount > country	Alphanumeric	2	Country of the bank account.
successfulItems[n] > bankAccount > documentNumber	Numeric	50	Identification number of the payee.
successfulItems[n] > bankAccount > documentType	Alphanumeric	2	Identification type of the payee.
successfulItems[n] > bankAccount > expeditionDate	Alphanumeric	10	Expedition date of the identity document of the payee.
successfulItems[n] > bankAccount > fullName	Alphanumeric		Full name of the payee.
successfulItems[n] > bankAccount > birthDate	Alphanumeric	10	Birth date of the payee.
successfulItems[n] > bankAccount > state	Alphanumeric		State of the Bank account.
successfulItems[n] > description	Alphanumeric		Additional information of the payout.
failedItems	List		List of items that failed during processing.
failedItems[n] > processingStatus	Alphanumeric	7	Status of the Payout request. For failed transactions, the value is `FAILED`.
failedItems[n] > failureMessages	List		List of error messages that generated the failure.
failedItems[n] > value	Numeric		Amount of the request.
failedItems[n] > bankAccount			This object has the information of the bank account that failed. This element has the same parameters than the object `successfulItems[n].bankAccount`.

The following request example sends three payouts:

The first and the second payout are requested for unregistered payees. The second one fails because the parameter bankCode has an invalid value.
The third payout is for a registered payee.

Request body:

{
  "transfers": [
    {
      "value": 1500000,
      "bankAccount": {
        "supplierType": "RELATED_THIRD_PARTY",
        "accountNumber": 2198922910000,
        "bankCode": "007",
        "accountType": "CC",
        "country": "CO",
        "documentNumber": 1026304116,
        "documentType": "CC",
        "expeditionDate": "1996-05-17",
        "fullName": "Santiago Romero Pineda",
        "birthDate": "1975-03-07",
        "merchantId": 510608
      },
      "description": "First Payment"
    },
    {
      "value": 2000000,
      "bankAccount": {
        "supplierType": "RELATED_PROVIDER",
        "accountNumber": 2198922910330,
        "bankCode": "8",
        "accountType": "CA",
        "country": "CO",
        "documentNumber": 102688116,
        "documentType": "CC",
        "expeditionDate": "2001-05-17",
        "fullName": "Juan Perez",
        "birthDate": "1985-04-17",
        "merchantId": 510608
      },
      "description": "Payment of supplies"
    },
    {
      "value": 4500000,
      "bankAccount": {
        "id": "e202507e-5551-4b67-be2a-a2a834bf1438"
      },
      "description": "Registered supplier payment"
    }
  ]
}

Response body:

{
    "totalSuccessful": 2,
    "totalFailed": 1,
    "successfulItems": [
        {
            "processingStatus": "SUCCESS",
            "paymentOrderId": "7202a9a7-ef51-4202-bd23-e604f9cbb25b",
            "value": 1500000.00,
            "bankAccount": {
                "processingStatus": "SUCCESS",
                "id": "e202507e-5551-4b67-be2a-a2a834bf1438",
                "supplierType": "RELATED_THIRD_PARTY",
                "accountNumber": "2198922910000",
                "bankCode": "007",
                "bankName": "BANCOLOMBIA",
                "accountType": "CC",
                "country": "CO",
                "documentNumber": "1026304116",
                "documentType": "CC",
                "expeditionDate": "1996-05-16T05:00:00.000+00:00",
                "fullName": "Santiago Romero Pineda",
                "birthDate": "1975-03-06T05:00:00.000+00:00",
                "state": "ACTIVE"
            },
            "description": "First Payment"
        },
        {
            "processingStatus": "SUCCESS",
            "paymentOrderId": "32740b81-5ecc-466c-bc09-699e6e5ceefb",
            "value": 4500000.00,
            "bankAccount": {
                "processingStatus": "SUCCESS",
                "id": "8f425a79-3f15-4e64-a1bf-2f7c087587ec",
                "supplierType": "RELATED_THIRD_PARTY",
                "accountNumber": "0200005555",
                "bankCode": "013",
                "bankName": "BBVA COLOMBIA",
                "accountType": "CA",
                "country": "CO",
                "documentNumber": "81856522",
                "documentType": "CC",
                "expeditionDate": "2002-02-17T05:00:00.000+00:00",
                "fullName": "Jorge Gutierrez",
                "birthDate": "1986-02-11T05:00:00.000+00:00",
                "state": "ACTIVE"
            },
            "description": "Registered supplier payment"
        }
    ],
    "failedItems": [
        {
            "processingStatus": "FAILED",
            "failureMessages": [
                "There is no registered bank with code: 8"
            ],
            "value": 2000000,
            "bankAccount": {
                "processingStatus": "FAILED",
                "supplierType": "RELATED_PROVIDER",
                "accountNumber": "2198922910330",
                "bankCode": "8",
                "accountType": "CA",
                "country": "CO",
                "documentNumber": "102688116",
                "documentType": "CC",
                "expeditionDate": "2001-05-17T00:00:00.000+00:00",
                "fullName": "Juan Perez",
                "birthDate": "1985-04-17T00:00:00.000+00:00"
            },
            "description": "Payment of supplies"
        }
    ]
}

Cancel payout request

This method lets you request the cancellation of a payout request. You can only request the cancellation of a Payout when its status is IN_PAYU_PROCESS or earlier. Refer to Payout states for more information.

Note

API Call

To cancel a Payout request, use the following URL:

DELETE
https://{env-api}.payulatam.com/v1.0/supplier-transfers/{merchantId}/{accountId}/{paymentOrderId}

The value for the variable {env-api} is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
merchantId	Merchant’s ID number in PayU’s system.	Yes
accountId	ID of the user account for each country associated with the merchant.	Yes
paymentOrderId	Payout ID generated when the order was created by the Request payout service.	Yes

Variables for request

Field name	Format	Size	Description	Mandatory
comments	Alphanumeric		Reason to cancel the Payout request.	No
pushPaymentId	Alphanumeric		Payout ID of the request to be cancelled.	No

The following are the request and response bodies for this method.

Request body:

{
  "comments": "Request cancellation for payout",
  "pushPaymentId": "1f92a225-9559-4b7f-9739-e6bb27b8b838"
}

Response body:

{
    "message": "Cancellation request received"
}

Create or Update a WebHook

This method lets you create or update a WebHook that allows you to configure a URL where PayU notifies states of a Payout via POST.

You can configure a WebHook for the following events:

Transfer creation: sends a notification when a payout request is created. To enable these notifications, include the TRANSFER_CREATION value in the list parameter enabledEvents.
Transfer update: sends a notification when the sanction screening validation rejects the payee. To enable these notifications, include the TRANSFER_UPDATE value in the list parameter enabledEvents.
Validation result: sends a notification when payee has approved the sanction screening validation and when the transfer has been rejected by the bank. To enable these notifications, include the VALIDATION_RESULT value in the list parameter enabledEvents.

Click here to know the variables in the notifications.

Note

API Call

To create a WebHook, use:

POST
https://{env-api}.payulatam.com/v1.0/webhooks/{merchantId}/{accountId}

To update a WebHook, use:

PUT
https://{env-api}.payulatam.com/v1.0/webhooks/{merchantId}/{accountId}

The value for the variable {env-api} is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
merchantId	Merchant’s ID number in PayU’s system.	Yes
accountId	ID of the user account for each country associated with the merchant.	Yes

Variables for request and response

Request parameters

Field name	Format	Size	Description	Mandatory
id	Alphanumeric		Id of the WebHook you want to update. This parameter is mandatory when updating a WebHook	No
accountId	Numeric		ID of the user account for each country associated with the merchant.	Yes
callbackUrl	Alphanumeric		URL used to receive the `POST` notifications sent by PayU according to the events selected. This URL must be unique per WebHook.	Yes
description	Alphanumeric		Description of the WebHook you want to create.	Yes
enabledEvents	List	Max:3	List of the events that will launch a notification to the configured URL when they occur. At least one event must be selected. Possibles values are: `TRANSFER_UPDATE`, `TRANSFER_CREATION`, `VALIDATION_RESULT`.	Yes

Response parameters

Field name	Format	Size	Description
id	Alphanumeric		Id of the WebHook created.
created	Date		Creation date of the WebHook. Format `YYYY-DD-MM hh:mm:ss`.
accountId	Numeric		ID of the user account for each country associated with the merchant.
callbackUrl	Alphanumeric		URL used that will receive the `POST` notifications according to the events selected.
description	Alphanumeric		Description of the WebHook created.
enabledEvents	List	Max:3	List of the events selected.
status	Alphanumeric	7	State of the WebHook. By default, the state of the new WebHook is `ENABLED`.
processingStatus	Alphanumeric	7	State of creation or update of the WebHook. By default, this state is `SUCCESS`.

The following are the request and response bodies for this method.

Request body:

{
  "accountId": 1,
  "callbackUrl": "https://wwww.callbackurltest.com/",
  "description": "Web Hook For Test Swagger",
  "enabledEvents": [
    "TRANSFER_UPDATE",
    "TRANSFER_CREATION",
    "VALIDATION_RESULT"
  ]
}

Response body:

{
    "processingStatus": "SUCCESS",
    "id": "256dd74e-9187-4efb-8238-fa29bf8f587a",
    "created": "2021-08-27T21:57:28.874+00:00",
    "accountId": 1,
    "callbackUrl": "https://wwww.callbackurltest.com/",
    "description": "Web Hook For Test Swagger",
    "enabledEvents": [
        "TRANSFER_UPDATE",
        "TRANSFER_CREATION",
        "VALIDATION_RESULT"
    ],
    "status": "ENABLED"
}

Delete a WebHook

This method lets you delete a WebHook previously created. As soon as you delete a WebHook, you stop receiving notifications.

Note

API Call

To delete a WebHook, use the following URL:

DELETE
https://{env-api}.payulatam.com/v1.0/webhooks/{merchantId}/{accountId}/{id}

The value for the variable {env-api} is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
merchantId	Merchant’s ID number in PayU’s system.	Yes
accountId	ID of the user account for each country associated with the merchant.	Yes
id	ID the WebHook you want to delete.	Yes

Response example

Field name	Format	Size	Description
processingStatus	Alphanumeric	7	State of deletion of the WebHook. By default, this state is `SUCCESS`.
id	Alphanumeric		Id of the WebHook deleted.
status	Alphanumeric	7	State of the WebHook. By default, the state of the deleted WebHook is `DELETED`.

{
    "processingStatus": "SUCCESS",
    "id": "054e0fc5-a025-4a00-b666-95673c11dee1",
    "status": "DELETED"
}

Query WebHooks

You can consult WebHooks related to your account either by their id or by the account id. Both methods are explained below.

Note

Query WebHooks by Id

This method lets you consult the information of a specific WebHook using its id. To query a WebHook, use the following URL:

GET
https://{env-api}.payulatam.com/v1.0/webhooks/{merchantId}/{accountId}/{id}

The value for the variable {env-api} is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
merchantId	Merchant’s ID number in PayU’s system.	Yes
accountId	ID of the user account for each country associated with the merchant.	Yes
id	ID the WebHook you want to query.	Yes

Response example

Response parameters

Field name	Format	Size	Description
processingStatus	Alphanumeric	7	State of query. By default, this state is `SUCCESS`.
id	Alphanumeric		Id of the WebHook.
created	Date		Creation date of the WebHook. Format `YYYY-DD-MM hh:mm:ss`.
accountId	Numeric		ID of the user account for each country associated with the merchant.
callbackUrl	Alphanumeric		URL used that will receive the `POST` notifications according to the events selected.
description	Alphanumeric		Description of the WebHook.
enabledEvents	List	Max:3	List of the events selected.
status	Alphanumeric	7	State of the WebHook. By default, the state of the new WebHook is `ENABLED`.

{
    "processingStatus": "SUCCESS",
    "id": "9628b74d-e2fb-40cc-b137-b156d1401641",
    "created": "2021-08-28T00:52:26.206+00:00",
    "accountId": 515058,
    "callbackUrl": "https://wwww.callbackurltest.com/",
    "description": "Web Hook For Test Swagger",
    "enabledEvents": [
        "TRANSFER_UPDATE",
        "TRANSFER_CREATION",
        "VALIDATION_RESULT"
    ],
    "status": "ENABLED"
}

Query webhooks by account

This method lets you consult the information of all the WebHooks created in your account. To query the WebHook list, use the following URL:

GET
https://{env-api}.payulatam.com/v1.0/webhooks/account/{merchantId}/{accountId}

The value for the variable {env-api} is sandbox-transfers for testing and transfers for production mode.

Parameter	Description	Mandatory
merchantId	Merchant’s ID number in PayU’s system.	Yes
accountId	ID of the user account for each country associated with the merchant.	Yes

Response example

Response parameters

Field name	Format	Size	Description
processingStatus	Alphanumeric	7	State of query. By default, this state is `SUCCESS`.
id	Alphanumeric		Id of the WebHook.
created	Date		Creation date of the WebHook. Format `YYYY-DD-MM hh:mm:ss`.
accountId	Numeric		ID of the user account for each country associated with the merchant.
callbackUrl	Alphanumeric		URL used that will receive the `POST` notifications according to the events selected.
description	Alphanumeric		Description of the WebHook.
enabledEvents	List	Max:3	List of the events selected.
status	Alphanumeric	7	State of the WebHook. By default, the state of the new WebHook is `ENABLED`.

[
    {
        "processingStatus": "SUCCESS",
        "id": "9628b74d-e2fb-40cc-b137-b156d1401641",
        "created": "2021-08-28T00:52:26.206+00:00",
        "accountId": 515058,
        "callbackUrl": "https://wwww.callbackurltest.com.co/",
        "description": "Web Hook For Test Swagger",
        "enabledEvents": [
            "TRANSFER_UPDATE",
            "TRANSFER_CREATION",
            "VALIDATION_RESULT"
        ],
        "status": "ENABLED"
    },
    {
        "processingStatus": "SUCCESS",
        "id": "672497c2-00f8-4787-a396-4024042eaa20",
        "created": "2021-09-15T16:04:49.131+00:00",
        "accountId": 515058,
        "callbackUrl": "https://wwww.callbackurltest.com.co/",
        "description": "Web Hook For Test Swagger",
        "enabledEvents": [
            "TRANSFER_UPDATE",
            "VALIDATION_RESULT"
        ],
        "status": "ENABLED"
    }
]

Last modified June 24, 2022: clon issue (d73e43fe5)