Sandbox Confirm

Use the sandbox confirm endpoints to close a pending PayIn or PayOut without waiting for a real bank or cash-network webhook. TumiPay updates the transaction, then sends the same merchant webhook it would send in a live flow. Typical cases:

Approve a PayIn that is waiting for confirmation (BREB, EFECTY, SPEI, QR, and others)
Approve, reject or expire a PayOut that is waiting for the bank
Exercise your ipn_url without waiting for an external webhook

These endpoints exist only in staging and UAT. They are not available in production.

Sandbox confirm does not create the transaction. Create it first with PayIn or PayOut, then confirm it once it is pending.

Availability


Environments	Staging and UAT only
Production	`404 NOT_FOUND` — no status change
Authentication	Same as other merchant APIs: `Authorization: Basic` + `Token-Top`

Base URL (staging): https://api-empresas.staging.topup.com.co/production Base URL (UAT): https://api-empresas.uat.topup.com.co/production.

Endpoints

Operation	Path
Confirm PayIn	`POST /api/v1/sandbox/payin/confirm`
Confirm PayOut	`POST /api/v1/sandbox/payout/confirm`

POST Confirm PayIn

Close a pending PayIn and fire the merchant webhook.

POST Confirm PayOut

Close a pending PayOut and fire the merchant webhook.

Use the PayIn endpoint only on PayIn transactions and the PayOut endpoint only on PayOut transactions. Mixing them returns 422 TYPE_MISMATCH.

Request

Headers

string

required

Basic authentication: Basic base64(username:password)

string

required

Merchant token. The transaction must belong to this merchant.

string

required

application/json

Body

The body is the same for PayIn and PayOut.

string

required

Identifier of the transaction. Accepts the TumiPay ticket, your merchant reference, or an external reference (Bre-B key, cash payment reference, SPEI CLABE, payout tracking id, and similar). See Identifiers.

string

required

Enum name in uppercase, not the portal label. Examples: SPEI, BREB, BANK_TRANSFER. Do not send "Transferencia SPEI".

string

required

Target status: APPROVED, REJECTED, or EXPIRED. Not every method supports every value — see Supported statuses.

{
  "transaction_id": "xiK9LSjwFyBYYRG",
  "payment_method": "SPEI",
  "status": "APPROVED"
}

Response

Success (`200`)

Repeating the same final status is idempotent: if the transaction is already in the requested status, the API still returns 200 SUCCESS.

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Transacción confirmada",
  "data": {
    "transaction_id": "xiK9LSjwFyBYYRG",
    "payment_method": "SPEI",
    "status": "APPROVED"
  }
}

Errors

HTTP	`error`	When
`404`	`NOT_FOUND`	Unknown `transaction_id`, another merchant’s transaction, or the endpoint is not enabled in this environment
`422`	`VALIDATION_ERROR`	Invalid body
`422`	`TYPE_MISMATCH`	PayIn confirm used on a PayOut (or the reverse)
`422`	`ALREADY_FINAL`	Transaction is already in a different final status
`422`	`STATUS_NOT_SUPPORTED`	That `status` is not valid for the payment method
`500`	`CONFIRM_FAILED`	Status update failed

Identifiers

transaction_id must belong to the merchant authenticated with Authorization + Token-Top. Any of these usually work:

What to send	Where it comes from	Example
Ticket	`data.ticket` from the create response	`xiK9LSjwFyBYYRG`
Merchant reference	`reference` you sent when creating the transaction	`XCL-2gyCSMzK2ditM`
External reference	Value returned in `payment_information` or assigned during processing	`@TUMI3785752657908`, cash payment reference, SPEI CLABE

Prerequisites

Flow	Before you call confirm
PayIn	Transaction exists and is still pending (not `APPROVED`, `REJECTED`, or `EXPIRED`)
PayOut	Transaction was submitted to the bank and is waiting for a response. A PayOut that was just created and not yet sent cannot be confirmed
PayOut Peru	Destination bank is in the sandbox catalog (BCP, Interbank, BBVA, Scotiabank, Yape, Plin, and similar). Banks outside that catalog — for example Santander — are often rejected at creation
PayOut Mexico (SPEI)	`account_type` is `CLABE`, both `account_number` and `clabe_number` use a test CLABE with a valid check digit, and the merchant has sandbox rates and balance

Not supported by sandbox confirm:

CARD — the result is fixed by the test card number.
PSE — create the PayIn with bank Banka and complete the normal PSE flow. See Testing.
NEQUI_PUSH — sandbox automatically simulates the push through the normal create flow (payment_url). See Colombia PayIn — NEQUI_PUSH.

Supported statuses

PayIn

`payment_method`	Country	`APPROVED`	`REJECTED`	`EXPIRED`
`BREB`	CO	✅	✅	❌
`BREB_QR`	CO	✅	✅	❌
`EFECTY`	CO	✅	❌	❌
`QR`	PE	✅	✅	✅
`SPEI`	MX	✅	❌	❌

Unsupported combinations return 422 STATUS_NOT_SUPPORTED.

PayOut

`payment_method`	Country	`APPROVED`	`REJECTED`	`EXPIRED`
`BANK_TRANSFER`	PE	✅	✅	✅
`BANK_TRANSFER`	CO	✅	✅	✅
`SPEI`	MX	✅	✅	✅

Method notes

Colombia PayIn — BREB and BREB QR

Use payment_method: "BREB" or "BREB_QR". Confirm while the PayIn is pending. transaction_id can be the ticket, your reference, or the Bre-B key from payment_information (for example @TUMI... / @TUMIQR...).Supported statuses: APPROVED, REJECTED.

Colombia PayIn — EFECTY

Use payment_method: "EFECTY". Confirm while the PayIn is pending. The cash payment reference from payment_information works as transaction_id.Only APPROVED is supported.

Peru PayIn — QR

Use payment_method: "QR". Ticket, merchant reference, or external reference are all valid.Supported statuses: APPROVED, REJECTED, EXPIRED.

Mexico PayIn — SPEI

Use payment_method: "SPEI". Confirm while the PayIn is pending. Ticket, merchant reference, or the CLABE assigned to the transaction work as transaction_id.Only APPROVED is supported.

Peru PayOut — BANK_TRANSFER

Use payment_method: "BANK_TRANSFER". The PayOut must already be waiting for the bank — not merely created.APPROVED completes the transfer. REJECTED and EXPIRED reject it (EXPIRED is treated as rejected) and restore sandbox balance.Create the PayOut with a bank from the sandbox catalog (BCP, Interbank, BBVA, Scotiabank, Yape, Plin, and similar). See Peru PayOut.

Colombia PayOut — BANK_TRANSFER

Use payment_method: "BANK_TRANSFER" with country: "CO". The PayOut must already be waiting for the bank.APPROVED completes the disbursement. REJECTED and EXPIRED reject it and restore sandbox balance.

Mexico PayOut — SPEI

Use payment_method: "SPEI" with account_type: "CLABE" and a valid test CLABE in both account_number and clabe_number.AHORRO, CORRIENTE, or an invented CLABE (for example 12345678…) usually reject the PayOut at creation, so sandbox confirm cannot run.Confirm only after the PayOut is waiting for the bank. See Mexico PayOut.

Mexico SPEI PayOut — test CLABEs (examples)

The following are example CLABEs for sandbox testing — not an exhaustive list. Use the same value in account_number and clabe_number:

`bank`	CLABE
`BBVA_MEXICO`	`012180015012345672`
`BANAMEX`	`002180015012345679`
`SANTANDER`	`014180015012345670`
`BANCOPPEL`	`137180015012345670`

What happens after confirm

Action	Effect
Approve PayIn	Status `APPROVED`, webhook to `ipn_url`, sandbox balance credited according to the method
Approve PayOut	Status `APPROVED`, webhook to `ipn_url`
Reject PayOut	Status `REJECTED`, reserved sandbox balance restored, webhook to `ipn_url`
Same status again	`200 SUCCESS` (idempotent)
Different final status	`422 ALREADY_FINAL`

Examples

Approve a Mexico SPEI PayIn

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/sandbox/payin/confirm' \
  --header 'Authorization: Basic your_auth_key' \
  --header 'Token-Top: your_auth_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "transaction_id": "7tt7nNt7Wf96qlz",
    "payment_method": "SPEI",
    "status": "APPROVED"
  }'

Approve a Peru PayOut

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/sandbox/payout/confirm' \
  --header 'Authorization: Basic your_auth_key' \
  --header 'Token-Top: your_auth_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "transaction_id": "XCL-2gyCSMzK2ditM",
    "payment_method": "BANK_TRANSFER",
    "status": "APPROVED"
  }'

Approve a Mexico SPEI PayOut

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/sandbox/payout/confirm' \
  --header 'Authorization: Basic your_auth_key' \
  --header 'Token-Top: your_auth_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "transaction_id": "A3abF5q3Bu15neI",
    "payment_method": "SPEI",
    "status": "APPROVED"
  }'

Reject a Mexico SPEI PayOut

{
  "transaction_id": "XCL-3jknH0UrmbksJ",
  "payment_method": "SPEI",
  "status": "REJECTED"
}

Approve a Colombia BREB PayIn

{
  "transaction_id": "@TUMI3785752657908",
  "payment_method": "BREB",
  "status": "APPROVED"
}

Quick reference by country

Country	PayIn sandbox confirm	PayOut sandbox confirm
Colombia	`BREB`, `BREB_QR`, `EFECTY`	`BANK_TRANSFER`
Peru	`QR`	`BANK_TRANSFER`
Mexico	`SPEI`	`SPEI`

Troubleshooting

Symptom	Likely cause
`404 NOT_FOUND`	Wrong `transaction_id`, another merchant’s token, or called against production
`TYPE_MISMATCH`	PayIn vs PayOut endpoint does not match the transaction
`STATUS_NOT_SUPPORTED`	For example `EXPIRED` on BREB or EFECTY PayIn, or `REJECTED` on SPEI PayIn
`ALREADY_FINAL`	The transaction was already closed by another flow or a previous confirm. Confirm only while it is still pending
Peru PayOut rejected at creation	Bank is outside the sandbox catalog (for example Santander)
Mexico PayOut rejected immediately	Invalid CLABE or `account_type` is not `CLABE`
PayOut confirm has no effect	Transaction is still in created state and has not reached “waiting for bank”
Card approved or declined unexpectedly	PAN is not from the test card table; sandbox confirm does not apply
PSE confirm fails or has no effect	PSE is not supported by sandbox confirm — use bank Banka in the normal PSE flow (Testing)

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

Sandbox Confirm

Sandbox Confirm

Sandbox Confirm

Availability

Endpoints

POST Confirm PayIn

POST Confirm PayOut

Request

Headers

Body

Response

Success (`200`)

Errors

Identifiers

Prerequisites

Supported statuses

PayIn

PayOut

Method notes

Mexico SPEI PayOut — test CLABEs (examples)

What happens after confirm

Examples

Approve a Mexico SPEI PayIn

Approve a Peru PayOut

Approve a Mexico SPEI PayOut

Reject a Mexico SPEI PayOut

Approve a Colombia BREB PayIn

Quick reference by country

Troubleshooting

​Sandbox Confirm

​Availability

​Endpoints

POST Confirm PayIn

POST Confirm PayOut

​Request

​Headers

​Body

​Response

​Success (200)

​Errors

​Identifiers

​Prerequisites

​Supported statuses

​PayIn

​PayOut

​Method notes

​Mexico SPEI PayOut — test CLABEs (examples)

​What happens after confirm

​Examples

​Approve a Mexico SPEI PayIn

​Approve a Peru PayOut

​Approve a Mexico SPEI PayOut

​Reject a Mexico SPEI PayOut

​Approve a Colombia BREB PayIn

​Quick reference by country

​Troubleshooting

Sandbox Confirm

Availability

Endpoints

Request

Headers

Body

Response

Success (`200`)

Errors

Identifiers

Prerequisites

Supported statuses

PayIn

PayOut

Method notes

Mexico SPEI PayOut — test CLABEs (examples)

What happens after confirm

Examples

Approve a Mexico SPEI PayIn

Approve a Peru PayOut

Approve a Mexico SPEI PayOut

Reject a Mexico SPEI PayOut

Approve a Colombia BREB PayIn

Quick reference by country

Troubleshooting