Skip to content
PachaPayPachaPayPachaPay Docs
Draft: the API is under development and may change before the first release

Create a payment (pay-in)

POST
/payments
curl --request POST \
  --url https://api.pachapay.io/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "amount": 100000, "currency": "CLP", "country": "CL", "method_code": "CL.KHIPU", "merchant_reference": "order-8841", "payer": { "name": "Maria Lopez", "email": "maria@example.com", "document": { "type": "RUT", "number": "12345678-5" } }, "return_url": "https://merchant.example/return" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
amount
required

Minor units.

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
merchant_reference

Your own order id.

string
<= 255 characters
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
return_url
string format: uri
flow

Hosted sends the payer to checkout_url, s2s lets you show next_action in your own UI.

string
default: hosted
Allowed values: hosted s2s
expires_in_seconds
integer
>= 60
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": 100000,
  "currency": "CLP",
  "country": "CL",
  "method_code": "CL.KHIPU",
  "merchant_reference": "order-8841",
  "payer": {
    "name": "Maria Lopez",
    "email": "maria@example.com",
    "document": {
      "type": "RUT",
      "number": "12345678-5"
    }
  },
  "return_url": "https://merchant.example/return"
}

Responses

Section titled “Responses”

201

Section titled “201”

Payment created. Follow next_action to complete it.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: payment
status
required

expired is not final: a late payment moves it to succeeded. partially_paid and overpaid apply to transfers. chargeback applies to cards.

string
Allowed values: created requires_action processing succeeded failed expired canceled on_hold partially_paid overpaid chargeback
amount
required

Amount the merchant asked for.

integer format: int64
amount_received
required

Amount actually received so far.

integer format: int64
fee

Our fee on the received amount, same currency.

integer format: int64
net_amount

Received amount minus fee.

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
method_family
required
string
Allowed values: card bank_redirect bank_transfer wallet cash deposit_reference
flow
string
Allowed values: hosted s2s deposit_reference
checkout_url

Hosted checkout page, set for the hosted flow.

string | null format: uri
refunded_amount

Total refunded so far in minor units.

integer format: int64
merchant_reference
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
next_action

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
failure_reason
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
expires_at
string | null format: date-time
succeeded_at
string | null format: date-time

Example 

{
  "id": "pay_0192f3a1",
  "object": "payment",
  "status": "created",
  "currency": "CLP",
  "country": "CL",
  "method_family": "card",
  "flow": "hosted",
  "payer": {
    "document": {
      "type": "RUT"
    }
  },
  "next_action": {
    "type": "redirect"
  }
}

429

Section titled “429”

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

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

Example 

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

Headers

Section titled “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

Section titled “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"
  }
}

5XX

Section titled “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"
  }
}