Payment, payout and refund events

POST

Sent to the merchant’s endpoint. Signed with the header PachaPay-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + raw_body). Reject events whose t is older than 5 minutes. The body is the full object, not just an id. Delivery is at least once: handle duplicates by event.id. Retries use increasing delays; respond with any 2xx to acknowledge.

Authorizations

• ApiKey

Parameters

Header Parameters

PachaPay-Signature

required

string

Example

t=1760517000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Request Body^required

Media typeapplication/json

object

id

required

Unique per event. Use it to ignore duplicates.

string

Example

evt_0192f3e5

object

required

string

Allowed value: event

type

required

string

Allowed values: payment.created payment.requires_action payment.succeeded payment.failed payment.expired payment.canceled payment.partially_paid payment.overpaid payment.chargeback payout.created payout.succeeded payout.failed payout.canceled payout.returned refund.succeeded refund.failed payment.processing payment.on_hold payout.processing payout.on_hold payout.delayed refund.created refund.processing refund.returned balance.updated

created_at

required

string format: date-time

data

required

One of: discriminator: object

object

object

id

required

string

Example

pay_0192f3a1

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

object

object

id

required

string

Example

pout_0192f3b7

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

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

Wallet

Wallet

object

type

required

string

Allowed value: wallet

phone

required

E.164 format.

string

holder_document

object

type

required

string

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

number

required

string

PIX key (Brazil)

PIX key (Brazil)

object

type

required

string

Allowed value: pix

key_type

required

string

Allowed values: cpf cnpj email phone random

key

required

string

holder_document

object

type

required

string

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

number

required

string

CLABE account (Mexico)

CLABE account (Mexico)

object

type

required

string

Allowed value: clabe

clabe

required

string

/^[0-9]{18}$/

holder_name

required

string

holder_document

object

type

required

string

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

number

required

string

Crypto wallet (merchant withdrawal)

Crypto wallet (merchant withdrawal)

object

type

required

string

Allowed value: crypto_wallet

network

required

string

Allowed values: TRON

token

required

string

Allowed values: USDT

address

required

Must be whitelisted; a new address becomes active after 24 hours.

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

object

object

id

required

string

Example

ref_0192f3c2

object

required

string

Allowed value: refund

status

required

string

Allowed values: created processing succeeded failed canceled returned

payment_id

required

string

payout_id

Set when the refund is executed as a payout.

string | null

amount

required

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

reason

string | null

created_at

required

string format: date-time

object

object

object

required

string

Allowed value: balance

currency

required

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

string

Allowed values: CLP COP PEN MXN BRL USD

available

required

Can be paid out. Never negative.

integer format: int64

pending

required

Waiting for settlement.

integer format: int64

reserve

required

Held against chargebacks.

integer format: int64

hold

required

Reserved for payouts and refunds in progress.

integer format: int64

debt

required

What the merchant owes after chargebacks. Payouts and refunds are blocked while it is above zero.

integer format: int64

updated_at

string format: date-time

Responses

200

Acknowledged.