Create a payout

POST

/payouts

const url = 'https://api.pachapay.io/v1/payouts';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"amount":50000,"currency":"CLP","country":"CL","method_code":"CL.BANK_TRANSFER","merchant_reference":"payout-1190","destination":{"type":"bank_account","bank_code":"001","account_number":"000123456789","account_type":"checking","holder_name":"Maria Lopez","holder_document":{"type":"RUT","number":"12345678-5"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.pachapay.io/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "amount": 50000, "currency": "CLP", "country": "CL", "method_code": "CL.BANK_TRANSFER", "merchant_reference": "payout-1190", "destination": { "type": "bank_account", "bank_code": "001", "account_number": "000123456789", "account_type": "checking", "holder_name": "Maria Lopez", "holder_document": { "type": "RUT", "number": "12345678-5" } } }'

The amount plus our fee is reserved from the merchant’s available balance at creation. If the balance is not enough, returns 422 insufficient_balance.

Authorizations

ApiKey

Parameters

Header Parameters

Idempotency-Key

required

string

<= 255 characters

Unique key per logical operation, up to 255 characters. Keys are kept for 24 hours. Same key with a different body returns 409 idempotency_conflict, and the same key while the first request is still running returns 409 idempotency_in_progress.

Request Body^required

application/json

object

amount

required

integer format: int64

>= 1

currency

required

ISO 4217 code. Crypto assets are not accepted in this field.

string

Allowed values: CLP COP PEN MXN BRL USD

country

required

ISO 3166-1 alpha-2. Target countries for the first release are CL, CO, EC, PE, MX and BR; availability per country depends on the agreement with the payment provider.

string

Allowed values: CL CO EC PE MX BR

method_code

required

string

destination

required

One of: discriminator: type

Bank account

object

type

required

string

Allowed value: bank_account

bank_code

string

account_number

required

string

account_type

string

Allowed values: checking savings vista other

holder_name

required

string

holder_document

required

object

type

required

string

Allowed values: RUT CC NIT CE PASS PPT RUC DL DNI CPP CPF CNPJ RFC CURP

number

required

string

merchant_reference

string

<= 255 characters

metadata

Up to 20 string keys, values up to 500 characters. Returned as is.

object

<= 20 properties

key

additional properties

string

<= 500 characters

Example

{
  "amount": 50000,
  "currency": "CLP",
  "country": "CL",
  "method_code": "CL.BANK_TRANSFER",
  "merchant_reference": "payout-1190",
  "destination": {
    "type": "bank_account",
    "bank_code": "001",
    "account_number": "000123456789",
    "account_type": "checking",
    "holder_name": "Maria Lopez",
    "holder_document": {
      "type": "RUT",
      "number": "12345678-5"
    }
  }
}

Responses

201

Payout created.

application/json

object

required

string

object

required

string

Allowed value: payout

status

required

After succeeded the bank may still return the money, then the status becomes returned.

string

Allowed values: created processing succeeded failed canceled on_hold returned

amount

required

integer format: int64

fee

Our fee; reserved on top of the amount.

integer format: int64

currency

required

ISO 4217 code. Crypto assets are not accepted in this field.

string

Allowed values: CLP COP PEN MXN BRL USD

country

required

ISO 3166-1 alpha-2. Target countries for the first release are CL, CO, EC, PE, MX and BR; availability per country depends on the agreement with the payment provider.

string

Allowed values: CL CO EC PE MX BR

method_code

required

string

destination

One of: discriminator: type

Bank account

object

type

required

string

Allowed value: bank_account

bank_code

string

account_number

required

string

account_type

string

Allowed values: checking savings vista other

holder_name

required

string

holder_document

required

object

type

required

string

Allowed values: RUT CC NIT CE PASS PPT RUC DL DNI CPP CPF CNPJ RFC CURP

number

required

string

merchant_reference

string

failure_reason

string | null

refund_id

Set when the payout executes a refund.

string | null

metadata

Up to 20 string keys, values up to 500 characters. Returned as is.

object

<= 20 properties

key

additional properties

string

<= 500 characters

created_at

required

string format: date-time

succeeded_at

string | null format: date-time

Example

{
  "id": "pout_0192f3b7",
  "object": "payout",
  "status": "created",
  "currency": "CLP",
  "country": "CL",
  "destination": {
    "type": "bank_account",
    "account_type": "checking",
    "holder_document": {
      "type": "RUT"
    }
  }
}

429

Too many requests. Retry after the number of seconds in Retry-After.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error invalid_state_error idempotency_error rate_limit_error api_error

code

required

Stable machine-readable code that does not change within a major version. Examples are parameter_invalid, parameter_missing, amount_out_of_range, api_key_invalid, api_key_revoked, merchant_not_active, method_not_allowed, country_not_allowed, resource_not_found, idempotency_conflict, idempotency_in_progress, invalid_state, insufficient_balance, method_not_available, blocked_payer, limit_exceeded, rate_limited, internal_error, provider_unavailable, service_unavailable.

string

message

required

string

param

Name of the offending parameter, if any.

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests left in the current window.

RateLimit-Reset

integer

Seconds until the window resets.

4XX

Error. See error.code.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error invalid_state_error idempotency_error rate_limit_error api_error

code

required

string

message

required

string

param

Name of the offending parameter, if any.

string

request_id

required

string

Examples

Merchant not approved

{
  "error": {
    "type": "permission_error",
    "code": "merchant_not_active",
    "message": "KYB is not approved for this merchant.",
    "request_id": "req_01"
  }
}

Not enough balance

{
  "error": {
    "type": "invalid_state_error",
    "code": "insufficient_balance",
    "message": "Available balance is lower than the amount plus fee.",
    "param": "amount",
    "request_id": "req_02"
  }
}

5XX

Error. See error.code.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error invalid_state_error idempotency_error rate_limit_error api_error

code

required

string

message

required

string

param

Name of the offending parameter, if any.

string

request_id

required

string

Examples

Merchant not approved

{
  "error": {
    "type": "permission_error",
    "code": "merchant_not_active",
    "message": "KYB is not approved for this merchant.",
    "request_id": "req_01"
  }
}

Not enough balance

{
  "error": {
    "type": "invalid_state_error",
    "code": "insufficient_balance",
    "message": "Available balance is lower than the amount plus fee.",
    "param": "amount",
    "request_id": "req_02"
  }
}

Create a payout

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

201

Example

429

Example

Headers

4XX

Examples

5XX

Examples

Request Body^required