Issue a permanent deposit reference for a payer

POST

/deposit-references

curl --request POST \
  --url https://api.pachapay.io/v1/deposit-references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "country": "CL", "currency": "CLP", "method_code": "example", "payer": { "name": "example", "email": "hello@example.com", "phone": "example", "document": { "type": "RUT", "number": "example" }, "ip": "example", "device_id": "example" }, "merchant_reference": "example" }'

• Production

Incoming transfers to this reference create payments automatically.

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

Media typeapplication/json

object

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

currency

required

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

string

Allowed values: CLP COP PEN MXN BRL USD

method_code

required

string

payer

object

name

string

email

string format: email

phone

E.164 format.

string

document

object

type

required

string

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

number

required

string

ip

Payer IP address, optional. Used for risk checks.

string

device_id

Opaque device identifier from the merchant, optional. Used for risk checks.

string

merchant_reference

For example the player id on the merchant side.

string

Responses

201

Deposit reference created.

Media typeapplication/json

object

id

required

string

object

required

string

Allowed value: deposit_reference

status

required

string

Allowed values: active disabled

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

currency

required

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

string

Allowed values: CLP COP PEN MXN BRL USD

method_code

required

string

merchant_reference

string

details

required

What the payer must do next. Show it or redirect the payer.

object

type

required

string

Allowed values: redirect qr voucher bank_transfer_details phone_otp none

redirect_url

string format: uri

qr_payload

string

voucher_code

string

voucher_barcode

string

bank_transfer

object

bank_name

string

account_number

string

account_holder

string

reference

Reference the payer must include.

string

expires_at

string format: date-time

created_at

required

string format: date-time

Example

{
  "id": "dep_0192f3d9",
  "object": "deposit_reference",
  "status": "active",
  "country": "CL",
  "currency": "CLP",
  "details": {
    "type": "redirect"
  }
}

4XX

Error. See error.code.

Media typeapplication/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

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.

Media typeapplication/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

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"
  }
}