Accept Colombian pesos (card, PSE, Bancolombia, Bre-B, Nequi, Daviplata)

What you will do

Pesos land in a separate COP balance, net of your COP fee (standard 4.5% + COP 1,500 per payment; see the Pricing page). The minimum per payment is COP 20,000. On the hosted checkout you price in USD and VEXPay shows the buyer the peso amount.

• COP enabled on your account by VEXPay.
• A webhook endpoint subscribed to payment.completed, payment.failed, payment.canceled and payment.reversed.

Steps: hosted checkout

1. 01
   Create a session

   POST /v1/checkout/sessions with amountUsd and methods containing cop (or no methods).

2. 02
   The buyer picks COP

   The checkout shows the peso total, then the channels your account offers (card first, then PSE).

3. 03
   The buyer completes the channel

   Bre-B: scan the QR or copy the key into any Colombian bank app (about 15 minutes). Nequi: approve the push in the app (about 5 minutes). Daviplata: type the 6-digit SMS code.

4. 04
   Fulfil from the webhook

   payment.completed with method: "COP", amountCop, feeCop, amountUsd and your checkoutSession reference.

Steps: your own screens (API)

1. 01
   Create the payment

   POST /v1/cop/payments with an Idempotency-Key header, amountCop (whole pesos, at least 20,000), channel (from GET /v1/cop/channels) and buyer (required for every channel except Bre-B: email, phone of 10 digits starting with 3, document type and number, plus termsAccepted: true when the catalog says needsTermsAcceptance; PSE also needs names, personType and pse.bankCode).

2. 02
   Show the next step

   The response next tells you what to show: show_qr (QR image and transfer key — returned only once), approve_in_app, submit_otp, redirect (send the buyer to next.url) or redirect_pending (read the payment again in a few seconds).

3. 03
   Daviplata only: send the code

   POST /v1/cop/payments/:id/otp with { "otp": "…" }. A wrong code can be retried while the payment is pending.

4. 04
   Wait for the result

   React to payment.completed or payment.failed, or read GET /v1/cop/payments/:id. Cancel a pending payment with POST /v1/cop/payments/:id/cancel.

curl --request POST "${API_URL}/v1/cop/payments" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --header "Idempotency-Key: order-5120" \
  --data '{
    "amountCop": 50000,
    "channel": "nequi",
    "reference": "order-5120",
    "buyer": { "email": "juan@example.com", "phone": "3001234567", "documentType": "CC", "documentNumber": "1234567890" }
  }'

Check that it worked

• Test Nequi: any valid data completes about a minute later. Test Daviplata: code 123456. Never send real pesos in Test.
• GET /v1/cop/payments/:id shows completed with feeCop.
• GET /v1/cop/balance shows the net in heldCop (Live) and later in availableCop.

Refund a peso payment

POST /v1/cop/payments/:id/refund refunds the full amount within 96 hours of completion. Your COP balance must cover the net amount that was credited; the COP fee is returned. You then receive payment.reversed with status: "refunded". See Refunds & chargebacks.

If something goes wrong

Fees: Pricing. Related: Colombia (COP) · Recipe: Colombian pesos · Convert to USDT