Create a deposit

Creates a deposit for your customer to pay with the payment method you chose from Get payment methods. The response tells you how your customer pays: a link to a Cashela-hosted payment page, or payment instructions.

POST/api/v1/pay-in/deposit-creation

Authentication	HTTP Basic (api_key:api_secret)
Moves money	Yes
Optional headers	Idempotency-Key, X-Trace-Id

Request body

The body has two parts: fixed fields, always required, and payer fields, which depend on the payment method.

Fixed fields (all required)

Field	Type	Description
payment_type	string	A payment type available for country (for example BANK_TRANSFER, CREDIT_CARD, VOUCHER).
payment_method	string	The payment_method code of the option returned by Get payment methods for this country and type.
amount	number	Positive, at most two decimals, from 0.01 to 99999999.99.
country	string	3-letter ISO code of the deposit’s country.
external_identifier	string (≤ 255)	Your unique id for this deposit (for example your order id). Unique per account. See Idempotency.
invoice_description	string (≤ 255)	What your customer is paying for. Plain text: HTML tags are rejected.
notification_url	string (≤ 255)	Your HTTPS endpoint for the signed notification. Must use https, must not embed credentials, and must not point to a private or internal address. See Webhooks.
redirect_url	string (≤ 255)	Valid https URL where your customer returns after the payment page. Its domain must be in your approved return URLs.
logo	string (≤ 255)	Absolute URL of your logo (for example https://partner.example.com/logo.png), shown on the payment page.
mobile	boolean	Whether your customer is on a mobile device. A boolean, not a phone number.
language	string	en or es: language of the payment page.
fee_on_payer	boolean	true adds the fees to what your customer pays; false deducts them from what is credited to you.
client_ip	string	Your customer’s public IP address (IPv4 or IPv6), not your server’s. For card payments its location must match country.

logo and client_ip are required

A request without logo or client_ip is refused with 422 and errors.logo / errors.client_ip. Booleans (mobile, fee_on_payer) must be JSON true/false: any other value is read as missing ("The mobile field is required.").

Payer fields (depend on the method)

Send every field listed in the chosen option’s required_fields / mandatory_fields, at the root of the JSON body, as strings of up to 255 characters. The usual ones are first_name, last_name, email, phone, document_key and document_number; depending on the country and method you may also need middle_name, second_last_name, address, city, region, zip_code or method-specific fields such as cbu (Argentina, 22 digits).

Their rules, the accepted documents and real validation messages are in Payer data & documents.

Example

curl https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "Idempotency-Key: order-2026-0001" \
  -H "X-Trace-Id: 6f1c2b7e-3a4d-4e5f-9a8b-1c2d3e4f5a6b" \
  -d '{
    "payment_type": "BANK_TRANSFER",
    "payment_method": "BX",
    "amount": 25.50,
    "country": "CHL",
    "external_identifier": "order-2026-0001",
    "invoice_description": "Order 2026-0001",
    "notification_url": "https://partner.example.com/webhooks/cashela",
    "redirect_url": "https://partner.example.com/orders/2026-0001",
    "logo": "https://partner.example.com/logo.png",
    "mobile": false,
    "language": "es",
    "fee_on_payer": true,
    "client_ip": "200.27.10.1",
    "first_name": "María José",
    "last_name": "Pérez",
    "email": "maria.perez@example.com",
    "phone": "+56912345678",
    "document_key": "RUT",
    "document_number": "12.345.678-5"
  }'

BX is an example code: always use a payment_method returned by Get payment methods for your account. All personal data in these examples is fictitious.

Response 200

The deposit, with its initial status. Values are illustrative.

{
  "success": true,
  "data": {
    "id": "1048576",
    "reference": "210000000000",
    "external_identifier": "order-2026-0001",
    "status": "PROCESSING",
    "status_message": null,
    "details": {
      "invoice_number": "INV-0001",
      "invoice_description": "Order 2026-0001",
      "invoice_country": "CHL",
      "invoice_currency": "CLP",
      "invoice_rate": 940.12,
      "invoice_fee": 0,
      "invoice_tax": 0,
      "invoice_amount": 23973.06,
      "customer": { "first_name": "María José", "last_name": "Pérez", "email": "maria.perez@example.com" },
      "paying": {
        "method": "Bank Transfer",
        "code": "BX",
        "name": "BX",
        "metadata": {
          "iframe": false,
          "redirect_url": "https://…",
          "validity_period": "2026-10-20T15:04:05+00:00"
        }
      },
      "charged_amount": 23973.06,
      "charged_currency": "CLP"
    },
    "card": null,
    "reversals": { "refunds": [], "disputes": [] }
  },
  "message": "Deposit created."
}

What to read

Field	Description
reference	Cashela’s reference of the deposit. Use it (or your external_identifier) in GET /transactions/{reference}. It is the ref in the notification.
status	Initial status, usually PROCESSING (waiting for your customer) or ONHOLD. INREVIEW means a document needs manual review: no payment link is issued yet. See statuses.
status_message	Human-readable detail when there is one.
details.invoice_*	The invoice your customer sees: country, currency, rate, fee, tax and amount in that currency.
details.customer	The payer data recorded for the deposit.
details.paying	How your customer pays: method, code, name, logo, and metadata (below).
details.paying.metadata.redirect_url	The payment link. Redirect your customer to it, or open it in a new window or tab. For cards it is a Cashela-hosted page (https://www.cashela.com/partner-checkout/{token} in production).
details.paying.metadata.validity_period	ISO-8601 date and time until which your customer can pay (about one hour for cards). After it, the deposit ends CANCELLED and nothing is charged.
details.paying.metadata.iframe	Always false: do not embed the payment page in an iframe.
details.paying.metadata (other keys)	For vouchers and transfers, the payment instructions may come here (for example digitable_line, qr_code, payment_info). Show them to your customer.
details.charged_amount, details.charged_currency	What your customer is charged. For card options that charge in USD this is the USD amount, while invoice_* is the local-currency estimate.
card	{ "network", "last4" } of the card that paid, or null (non-card methods, or before the charge).
reversals	Voids and refunds of the deposit, if any.

Note

The payment instructions in details.paying.metadata are only returned while the deposit can still be paid. Once it is final, they are no longer included.

Approved return URLs

Your customer is only sent back to a redirect_url whose domain you have approved. Manage the list yourself in the Developer Portal of your Dashboard: open an API key (the eye icon) and use its Allowed return URLs:

• Add the URL or just the domain (for example https://checkout.yourstore.com or checkout.yourstore.com); only https is accepted and Cashela keeps the domain.
• You can approve several domains (up to 20). The list belongs to each API key, so a key only accepts the domains approved for it.
• A subdomain of an approved domain is accepted too (pay.yourstore.com for yourstore.com).
• Approve your test and production domains before you create deposits that use them. A redirect_url on a domain that is not approved is rejected with a validation error (422).

Idempotency and safe retries

Creating a deposit moves money, so a retry must never create a second one.

• Every deposit carries your unique external_identifier. Store it before you call the API.
• You may also send an Idempotency-Key header. If you do not, the external_identifier is the key.
• Keys are scoped to your credentials and environment.

You repeat the request with…	Result
The same key and the same body	200 with the original deposit. Nothing new is created and nothing is charged twice.
The same key and a different body	409 PARTNER_PAYIN_IDEMPOTENCY_CONFLICT: “A deposit already exists for this external_identifier or idempotency key with a different payload.” Nothing is created.

If the original request failed (for example the payment network rejected it), repeating it returns the same failure without trying again. To try again with corrected data, use a new external_identifier.

After a timeout or a 5xx, retry with the same key and body, or read the deposit with GET /api/v1/pay-in/transactions/{external_identifier} before deciding.

Validation and errors

A 422 with errors means nothing was created or charged. Fix the fields and send again.

{
  "success": false,
  "status": false,
  "message": "The logo field is required.",
  "errors": {
    "logo": ["The logo field is required."]
  }
}

errors lists every invalid field with its messages; message is a human-readable summary. status: false is a deprecated alias of success: false; read success. Some accounts also receive field_errors[] (one entry per field with field, code and expected_format).

Common domain errors on this endpoint:

HTTP	Code	What to do
404	PARTNER_PAYIN_PAYMENT_METHOD_NOT_FOUND	The method is not available for that country, account or environment. List the methods again.
404	PARTNER_PAYIN_COUNTRY_NOT_FOUND	Unknown country.
403	PARTNER_PAYIN_RAIL_NOT_ENABLED_FOR_TENANT	This payment method is not enabled for your account. Contact Cashela.
409	PARTNER_PAYIN_IDEMPOTENCY_CONFLICT	Same key, different body. See above.
409	PARTNER_PAYIN_EXTERNAL_IDENTIFIER_CONFLICT	A deposit with this external_identifier already exists.
422	PARTNER_PAYIN_AMOUNT_BELOW_MINIMUM / PARTNER_PAYIN_AMOUNT_ABOVE_MAXIMUM	The amount is outside the method’s limits. The message gives the limit.
422	PARTNER_PAYIN_ROUTE_UNAVAILABLE	The method is temporarily unavailable. List the methods again and choose another, or retry later.
422	PARTNER_PAYIN_PROVIDER_REJECTED	The payment network refused the deposit, usually because of the payer data. When it can, the response names the field in provider_reason. Correct it and retry with a new external_identifier.
422	PARTNER_PAYIN_COMPLIANCE_BLOCKED	The deposit cannot be created for compliance reasons.
502	PARTNER_PAYIN_PROVIDER_ERROR	The payment network failed. Read the deposit before sending a new request.

The code field is optional: read it when present, but do not require it. Full list: Errors.

After creating the deposit

1. Send your customer to details.paying.metadata.redirect_url, or show the instructions.
2. Wait for the signed notification on your notification_url.
3. If it does not arrive, read the deposit with Get a deposit or ask for it again with the re-send endpoint.