Overview

Learn everything you need to create a payout in Localpayment.

What is a Payout?

A Payout is the solution that allows you, via API or manual batch upload, to pay your local service providers, suppliers, gig workers, wallet withdrawals, remittances, and partners in Latin America. The Payout is executed in the local currency of a specific country and may or may not include FX depending on the account configuration.



Payout Flow

The payouts in local payments follow this flow:

  1. Merchant integrates with Localpayment and creates a new payment.

📘

Info

Either the Panel or the API can be used to request a payout.

  1. The settlement is received, and LP processes the payout request.
  2. LP executes payout amounts due to the beneficiaries.
  3. LP confirms in real-time the payment to the merchant.
  4. The merchant confirms the payment to the beneficiaries.


Available countries

Click on each available country in Localpaymenr to find out its currency, document type, minimum and maximum amounts, and SLA:




Prerequisites

Before requesting a payout, you must have completed the following steps:

1. Environment access

You will need to conclude your onboarding process and your Stage login credentials or your Production credentials (if you are already certified) in order to create a payment via API or Panel.

⚠️

Important

To produce a payout, make sure you have the appropriate user permissions.


2. Whitelist your IP

⚠️

Important

If you are going to create the payout via the Panel skip this step.

Before using the APIs, you must whitelist your IP address in the Panel to ensure secure access to LocalPayment services.


3. Generate an Authentication Token

⚠️

Important

If you are going to create the payout via the Panel skip this step.

To interact with LocalPayment's APIs, you need an authentication token.

Send a POST request to the Generate an Acces Token endpoint and include your API credentials in the request; to generate an authentication token.

Request example

curl --request POST \
     --url https://api.stage.localpayment.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "username": "[email protected]",
  "password": "1234"
}
'

Successful response

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlciI6dHJ1ZSwiaXNfc3RhZmYiOnRy3VudHJpZXMiOljpbIkFsiQUxMIl0sImNvbXBhbnkiOiJBTEwiLCJjbGllbnRfY29kZSI6IkFMTCIsInBlcm1pc3Npb25zIjpdWUsInJvbGVzIMTCJdLlqEnH7GrECJjbbXX0.sWOLKFxCcXQkUcPvTjYceXBp39hDF3-Snc"
}

📘

Info

For security reasons, access tokens are valid for 5 minutes. If your token expires, you can create a new one with a 24-hour validity by using the Refresh the token endpoint.


4. Consult the required code

  • Country:
    To get the Country in ISO format, check the list that is available in the documentation's Countries, choose the country of interest and navigate to the Country Overview section.

  • Currency:
    To get the Currency Code, check the list that is available in the documentation's Countries, choose the country of interest and navigate to the Country Overview section.

  • Payment method code:

    To get the payment method's code, check the list that is available through API or in the documentation's Countries, choose the country of interest and navigate to the Outgoing Payments (Payouts) section.

    To get it via the API, make a GET request to the Available Payment Methods endpoint. Review the response to find the Code for the payment method.

Request example

curl --request GET \
     --url 'https://api.stage.localpayment.com/api/resources/payment-methods?accountNumber=123.456.78900001' \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMD' \
     --header 'accept: application/json'

Successful response

[
  {
    "accountCode": "TESTARGUSD01",
    "accountNumber": "123.456.78900001",
    "countryISOCode3": "ARG",
    "moR": null,
    "mid": "0",
    "payinPaymentMethods": [
      {
        "id": 30,
        "code": "1005",
        "name": "Visa",
        "description": "Visa",
        "url": "https://cdn.localpayment.com/logos/visa-debit.png",
        "paymentMethodType": "DebitCard",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 24,
        "code": "1023",
        "name": "ITAU",
        "description": "ITAU",
        "url": "https://cdn.localpayment.com/logos/itau.png",
        "paymentMethodType": "BankTransfer",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 19,
        "code": "1000",
        "name": "Visa",
        "description": "Visa",
        "url": "https://cdn.localpayment.com/logos/visa.png",
        "paymentMethodType": "CreditCard",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 23,
        "code": "1004",
        "name": "Santander",
        "description": "Santander",
        "url": "https://cdn.localpayment.com/logos/santander.png",
        "paymentMethodType": "BankTransfer",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 21,
        "code": "1002",
        "name": "Pago facil",
        "description": "Pago Facil",
        "url": "https://cdn.localpayment.com/logos/pagoFacil.png",
        "paymentMethodType": "Cash",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      }
    ],
    "payoutPaymentMethods": [
      {
        "id": 87,
        "code": "2000",
        "name": "BBVA",
        "description": "Banco Frances",
        "url": null,
        "paymentMethodType": "BankTransfer",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      }
    ]
  }
]

  • Beneficiarie’s Bank’s Code:
    To get the beneficiary’s bank's code, check the list that is available through API or in the documentation's Countries, choose the country of interest and navigate to the Supported Banks section.

    To get it via the API, make a GET request to the Bank codes endpoint. Review the response to find the Code for the beneficiary's bank.

Request example

curl --request GET \
     --url 'https://api.stage.localpayment.com/api/resources/banks?name=ABC%20Capital' \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9vvvv' \
     --header 'accept: application/json'

Successful response

{
  "data": [
    {
      "id": 161,
      "code": "138",
      "bankType": "Bank",
      "name": "ABC Capital",
      "swift": "",
      "countryId": 50,
      "countryISOCode3": "MEX",
      "countryDesc": "Mexico",
      "additionalInformation": "40138",
      "checkingRegex": "[0-9]{10,18}",
      "savingRegex": "[0-9]{10,18}",
      "branchRegex": null,
      "isEnabled": true,
      "transactionTypes": [
        "PayIn",
        "PayOut"
      ]
    }
  ],
  "total": 94,
  "offset": 93
}

  • Concept Codes
    To get the Concept Code, check the list that is available in the documentation’s Concept Codes.

5. Validate the parties identity document

Validate the identity document format of the beneficiary, sender, and merchant.

Send a POST request to the Validate Identity Document endpoint. The API will respond with a code and adescription with the result of the validation.

Request example

curl --request POST \
     --url https://api.stage.localpayment.com/api/validation/document \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9vvvv' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"country":"ARG"}'

Successful response

{
  "code": "200",
  "description": "Valid id and type document"
}


Create a Payout

Initialize the payout transaction; you can achieve this action via the Panel or using the API service.

To create it via the API, send a POST request to the Create a Payout endpoint with all the required information of the transaction. The API will respond with the transaction information.


📘

Info

For details about a particular country and payment method, see PAYOUTS>Payment methods articles.


Request example

curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9vvvv' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "currency": "ARS",
    "paymentMethod": {
      "flow": "DIRECT",
      "code": "0010"
    },
    "beneficiary": {
      "type": "INDIVIDUAL",
      "document": {
        "type": "RUC",
        "id": "1791234561009"
      },
      "phone": {
        "countryCode": "55",
        "areaCode": "55",
        "number": "5555555"
      },
      "address": {
        "street": "Independencia",
        "number": "123",
        "city": "Cordoba",
        "state": "Cordoba",
        "country": "Argentina",
        "zipCode": "X5000IUO",
        "comment": "Sucursal 123"
      },
      "bank": {
        "account": {
          "number": "0070145330004020870169",
          "type": "C"
        },
        "branch": {
          "code": "172345",
          "name": "Branch Name"
        },
        "name": "Banco name",
        "code": "007",
        "CountryISOCode3": "ARG"
      },
      "name": "Beneficiary Name",
      "lastName": "Beneficiary LastName",
      "email": "[email protected]",
      "birthDate": "1990-01-01",
      "userReference": "Additional information",
      "nationality": "Beneficiary Nationality"
    },
    "sender": {
      "type": "COMPANY",
      "document": {
        "type": "RUC",
        "id": "1791234561009"
      },
      "name": "Sender Name",
      "lastName": "Sender LastName",
      "birthDate": "2001-01-01",
      "nationality": "Sender Nacionality"
    },
    "merchant": {
      "type": "INDIVIDUAL ",
      "name": "Merchant Name",
      "lastName": "Merchant LastName"
    },
    "conceptCode": "0006",
    "externalId": "12345678",
    "amount": 20423,
    "country": "ARG",
    "accountNumber": "{{account_arg_ars}}"
  }
]
'

Successful response

[
  {
    "externalId": "1736491418",
    "internalId": "7259d170-b74a-4112-8e93-cd832648c33a",
    "paymentMethod": {
      "code": "0010",
      "name": "INTERBANKING",
      "description": "string",
      "paymentMethodType": "BankTransfer"
    },
    "country": "ARG",
    "currency": "ARS",
    "amount": 20423,
    "accountNumber": "032.032.00000078",
    "clientCode": "0001",
    "clientName": "Acme",
    "status": {
      "code": "100",
      "description": "Received",
      "detail": "The payout was received"
    },
    "beneficiary": {
      "bank": {
        "name": "Banco name",
        "code": "007",
        "countryISOCode3": null,
        "branch": {
          "name": "Branch Name",
          "code": "Nro Branch"
        },
        "account": {
          "number": "0070145330004020870169",
          "type": "S",
          "alias": null,
          "pixKey": null,
          "phone": null
        }
      },
      "type": "INDIVIDUAL",
      "name": "Beneficiary Name",
      "lastname": "Beneficiary LastName",
      "document": {
        "type": "CUIL",
        "id": "20115872045"
      },
      "userReference": "Additional information",
      "email": "[email protected]",
      "phone": {
        "countryCode": "55",
        "areaCode": "55",
        "number": "5555555"
      },
      "birthdate": "1990-01-01T00:00:00",
      "nationality": "Beneficiary Nationality",
      "address": {
        "street": "Av Beneficiary Address",
        "number": "1234",
        "city": "City Name",
        "state": "State Name",
        "country": "Country Name",
        "zipCode": "Zip Code",
        "comment": "Additional address information"
      }
    },
    "merchant": {
      "type": "COMPANY",
      "name": "Merchant Name",
      "lastname": "Merchant LastName",
      "document": {
        "type": "Type Document",
        "id": "ID Document"
      },
      "userReference": "additional information",
      "email": "[email protected]",
      "phone": {
        "countryCode": "55",
        "areaCode": "55",
        "number": "66666666"
      },
      "birthdate": "2001-01-01T00:00:00",
      "nationality": "Merchant Nacionality",
      "address": {
        "street": "Av Merchant Address",
        "number": "1234",
        "city": "City Name",
        "state": "State Name",
        "country": "Country Name",
        "zipCode": "Zip Code",
        "comment": "Additional address information"
      }
    },
    "sender": {
      "type": "INDIVIDUAL",
      "name": "Sender Name",
      "lastname": "Sender LastName",
      "document": {
        "type": "CUIL",
        "id": "12345678901"
      },
      "userReference": "additional information",
      "email": "[email protected]",
      "phone": {
        "countryCode": "55",
        "areaCode": "57",
        "number": "7777777"
      },
      "birthdate": "2001-01-01T00:00:00",
      "nationality": "Sender Nacionality",
      "address": {
        "street": "Av Sender Address",
        "number": "1234",
        "city": "City Name",
        "state": "State Name",
        "country": "Country Name",
        "zipCode": "Zip Code",
        "comment": "Additional address information"
      }
    },
    "comment": "Addicional informetion",
    "exchangeRateToken": null,
    "date": {
      "creationDate": "2025-01-10T06:43:36.646148+00:00",
      "processedDate": "2025-01-10T06:43:36.646442+00:00"
    },
    "errors": null,
    "internalLoteID": "34704"
  }
]

📘

Info

Check the posible transaction status that you may obtein as response.



Next Steps

Authorize a Payout

If the payout was created by API and requireAuth was set as True or if the payout was generated in the Panel an additional authorization is required to complete the transaction.

If the payout was made using the Panel, a different user with authorization permissions must complete the authorization in the Panel .

If the payout was made by API, send a POST request to the Authorize a Payout endpoint, you can authorize a payout by internalId, externalId, or by a Date range to authorize all eligible payouts within that period.

Request example

curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/authorize \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9vvvv' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "externalId": "123456"
}
'

Successful response

{
  "status": 200,
  "message": "The request will be processed."
}

Cancel a Payout

If for any error you need to cancel a payout, you can do it as long as it is in Pending Authorization, Received, On Hold, or Locked status. For this action, you can do it by Panel or by API.

To cancel it via the API, send a PATCH request to the Void a Payout endpoint with all the required information of the transaction. The API will respond with the new status information.

Request example

curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payout/cancel \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNT' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "externalId": "1736488554"
}
'

Successful response

{
  "externalId": "1736488510",
  "internalId": "3d36811d-1c02-41ea-a576-68df62c4603a",
  "status": {
    "code": "900",
    "description": "Cancelled",
    "detail": "The payout was cancelled"
  }
}

Webhooks/Callbacks

If you have your notifications enabled, you will receive a message (webhook) to let you know when the status of your payout changes. Look for some webhook payout examples.


Obtain the Proof of Payment

If you need the Proof of Payment (POP) for one or more payouts, you can download it from the Panel.


Obtain the transaction information

You can consult the transaction information using the API or the Panel .By API, send a GET request to the Get transaction information endpoint with the required information of the transaction. The API will respond with the complete information of the transaction.

Request example

curl --request GET \
     --url https://api.stage.localpayment.com/api/transactions/1678374439 \
     --header 'Authorization: eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119' \
     --header 'accept: application/json'

Successful response

{
    "transactionType": "payOut",
    "externalId": "1678374439",
    "internalId": "5d264208-8d6c-4bdb-8387-f96d112258a5",
    "paymentMethod": {
        "code": "0050"
    },
    "country": "CHL",
    "currency": "USD",
    "amount": 504.0,
    "accountNumber": "152.840.00000005",
    "confirmed": {
        "currency": "USD",
        "fxQuote": 1.0,
        "amount": 504.0
    },
    "payment": {
        "currency": "CLP",
        "fxQuote": 761.07328245,
        "amount": 383581.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "USD",
        "fxQuote": 1.0,
        "amount": 2.5
    },
    "status": {
        "code": "200",
        "description": "Completed",
        "detail": "The payout was debited"
    },
    "sender": {
        "type": "INDIVIDUAL",
        "name": "Sender Name"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Prueba ",
        "document": {
            "type": "RUT",
            "id": "12.574.922-4"
        },
        "bank": {
            "name": "Banco Name",
            "code": "031",
            "account": {
                "type": "C",
                "number": "123456789012345"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Merchant Name"
    },
    "date": {
        "creationDate": "2023-03-09T15:07:18.128",
        "processedDate": "2023-03-09T15:07:18.397"
    }
}

Obtain the transaction status

You can consult the transaction status using the API or the Panel. For details about the possible status for a particular payment method, see PAYOUTS>Payment methods articles.

By API, send a GET request to the Get transaction status endpoint with the required information of the transaction. The API will respond with the status of the transaction.

Request example

curl --request GET \
     --url https://api.stage.localpayment.com/api/transactions/1678374439/status \
     --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNT' \
     --header 'accept: application/json'

Successful response

{
    "internalId": "5d264208-8d6c-4bdb-8387-f96d112258a5",
    "externalId": "1678374439",
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payout was debited.."
    }
}

Reimbursements

There are two possible reimbursement options in a payout:

  • Return: Is the process that occurs after a payout is completed; however, because the ACH domestic network is asynchronous, the beneficiary bank rejects the payment t+x days later. In consequence, the total amount of the transaction plus any applicable taxes and fees will be credited back.
  • Recall: Is the process of recovering a payout when the incorrect beneficiary wire information was provided by the merchant.