Payments

Online charges for an order: create a payment intent, read it, and run the interactive two-step Sypago (Débito Inmediato) flow. Provider confirmation webhooks land here too. Paths are relative to the /api/v1 prefix; all routes require Authorization: Bearer {token} except the public provider webhook.

Manual, form-based payments (bank transfer, Pago Móvil, etc.) live under Payment forms. The catalog of selectable methods is Payment methods. See also the order lifecycle.

See Common errors.

Endpoints

The payment object

The payment key is the payment record. Money is exposed as *_usd (decimal) alongside *_cents. expires_at is the payment window deadline.

{
  "payment": {
    "id": 9,
    "order_id": 42,
    "user_id": 1,
    "method": "SYPAGO_DI",
    "provider": "SYPAGO",
    "payment_form_id": null,
    "internal_type": null,
    "status": "PENDING",
    "amount_cents": 2020,
    "amount_bs_cents": null,
    "bcv_rate_cents": null,
    "reference": null,
    "provider_ref": null,
    "receipt_url": null,
    "reported_at": null,
    "expires_at": "2026-06-26T12:15:00.000000Z",
    "confirmed_at": null,
    "currency": "USD",
    "created_at": "2026-06-26T12:00:00.000000Z",
    "updated_at": "2026-06-26T12:00:00.000000Z",
    "amount_usd": 20.2,
    "aguita_revenue_usd": 3.6,
    "solidary_fund_usd": 0.36
  }
}

amount_cents / amount_usd is the order's client_charged_*, i.e. the total after any promotional credit — not client_pays_*.

POST /payments/webhook/{provider}

Public endpoint that providers call to confirm a charge. There is no session auth; the {provider} path segment (e.g. sypago) selects the provider. The webhook accepts a provider-defined body.

Response 204 No Content on a verified, applied event.

Errors

POST /settlements/webhook/sypago

SyPago payout (dispersion) confirmation callback for the driver-settlement (liquidación) module — distinct from the customer-charge webhook above. Public, but authenticated by a shared secret in the URL (?token=…) rather than a bearer token. Accepts GET or POST.

Request body (provider-sent; only the fields below are read — amount and receiving_user are echoed from the original payout and ignored)

Response 200 — { "message": "ok" } for any well-formed, authorized call, including an unknown or already-resolved internal_id.

Errors

POST /orders/{orderId}/payment

Creates (or refreshes) the payment intent for the caller's order. method must resolve to a known method; to change the order's method use PATCH /orders/{orderId}/payment-method.

Request body

Response 200

{
  "payment": { "id": 9, "status": "PENDING", "method": "PAGO_MOVIL", "amount_usd": 20.2 },
  "checkoutUrl": "https://checkout.example/pay/abc123"
}

checkoutUrl is the provider redirect/checkout link when applicable.

Errors

GET /orders/{orderId}/payment

Returns the payment associated with the order. Owner only.

Response 200 — { "payment": { … } }. See the payment object.

Errors

POST /orders/{orderId}/payment/prepare

Sypago step 1. Triggers the bank OTP to the payer. The order must use Débito Inmediato (SYPAGO_DI), be in WAITING_FOR_PAYMENT, and belong to the caller.

Request body

Response 200 — { "prepared": true, "payment": { … } }.

Errors

POST /orders/{orderId}/payment/report

Sypago step 2. Submits the OTP the payer received and finalizes the charge. Same ownership/method/state gating as prepare.

Request body

Response 200 — { "payment": { … } }.

Errors

Examples

# Sypago (Débito Inmediato): step 1 triggers the bank OTP
curl -X POST /api/v1/orders/42/payment/prepare \
  -H "Authorization: Bearer {client_token}" \
  -H "Content-Type: application/json" \
  -d '{"bank_code": "0102", "id_number": "V-12345678", "phone": "+584241000001"}'

# Step 2 submits the OTP the payer received
curl -X POST /api/v1/orders/42/payment/report \
  -H "Authorization: Bearer {client_token}" \
  -H "Content-Type: application/json" \
  -d '{"bank_code": "0102", "id_number": "V-12345678", "phone": "+584241000001", "otp": "123456"}'