Docs
Search the docs
Find a page in the docs

Guides

Payments

Charge a tokenized payment method and follow the payment to a final status.

A payment charges a payment method on one of your connections. Your page collects the card with the provider's own tokenization (Mercado Pago's Card Payment Brick or Stripe Elements, for example), and your server sends the token to Camel. Card numbers never reach your server or Camel.

Don't want to build a payment form? Use a checkout instead. PayPal and Ualá only work through checkouts.

Create a payment

curl -X POST https://api.camelpayment.com/v1/payments \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: order-1524" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mercadopago",
    "connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
    "amount": 1500000,
    "currency": "ARS",
    "description": "Order #1524",
    "external_reference": "ORDER-1524",
    "payment_method": {
      "type": "card",
      "token": "ff8080814c11e237014c1ff593b57b4d",
      "installments": 1
    },
    "customer": {
      "email": "buyer@example.com"
    },
    "metadata": {
      "order_id": "1524"
    }
  }'

Camel sends the charge to the provider and answers with the result. Most card payments are final in that response:

201 Created
{
  "id": "pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA",
  "object": "payment",
  "provider": "mercadopago",
  "connection_id": "con_01JBX7P8H2D4F6G8J0K2M4N6QR",
  "provider_payment_id": "1342345678",
  "amount": 1500000,
  "currency": "ARS",
  "conversion": null,
  "usd_amount": 971,
  "status": "approved",
  "provider_status": "approved",
  "description": "Order #1524",
  "external_reference": "ORDER-1524",
  "payment_method": {
    "type": "card",
    "brand": "visa",
    "last4": "4242"
  },
  "failure": null,
  "metadata": {
    "order_id": "1524"
  },
  "next_action": null,
  "created_at": "2026-11-12T15:04:05Z",
  "updated_at": "2026-11-12T15:04:07Z"
}

Set external_reference to your order id: it comes back in every response and webhook, and you can filter payments by it. See all fields in Create a payment.

Payment statuses

StatusMeaning
pendingCreated, waiting for the customer or the provider.
processingThe provider is still deciding.
requires_action The customer must do something, such as 3-D Secure. Details are in next_action.
approvedThe money was charged. Fulfil the order.
rejectedThe provider declined it.
cancelledCancelled before it was charged.
failedAn error, or a chargeback after approval on Mercado Pago.
expiredNever completed in time.
unknown The provider's answer was lost (a timeout). Camel is finding out; don't retry with a new key.
partially_refundedPart of the amount was refunded.
refundedThe whole amount was refunded.

rejected, cancelled, failed, expired, and refunded are final. The provider's own status is always in provider_status.

Follow the payment

Payments that aren't final yet change later. Camel learns about it from the provider and sends you a webhook such as payment.approved. Older provider events never overwrite a newer status. You can also retrieve the payment at any time:

curl https://api.camelpayment.com/v1/payments/pay_01JBX7Q2M4N8K5R6T9V3W1Y0ZA \
  -H "Authorization: Bearer $CAMEL_API_KEY"