Create Deposit Transaction

This endpoint creates a new PayIn deposit transaction, supporting multiple payment methods across different countries and currencies. The API returns transaction details and metadata required to complete the payment flow (redirect URL, iframe parameters, or payment instructions).

Endpoint

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

Authentication: Basic Auth (Business Key + Business Secret)

Base URLs:

Sandbox: https://sandbox-api.cashela.com
Production: https://api.cashela.com

Required Headers

Authorization: Basic <base64_encoded_credentials>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <uuid-v4>

Idempotency Key Requirements:

Must be a valid UUID v4
Unique per transaction attempt
Safe to retry with the same key if the request fails
Keys are retained for 24 hours
Using the same key with different request body returns 409 IDEMPOTENCY_CONFLICT

Request Parameters

Body Parameters

Parameter	Type	Required	Description
`country`	string	Yes	ISO 3-letter country code (e.g., `MEX`, `BRA`, `USA`). See Get Countries.
`amount`	number	Yes	Deposit amount in the specified currency. Decimals allowed (e.g., `100.50`).
`payment_type`	string	Yes	Payment type: `BANK_DEPOSIT`, `BANK_TRANSFER`, `CREDIT_CARD`, `MOBILE_MONEY`, `VOUCHER`, `WALLET`.
`payment_method`	string	Yes	Specific method code (e.g., `VI` for Visa, `OXXO` for OXXO cash). See Get Payment Methods.
`external_identifier`	string	Yes	Your unique transaction reference. Used for idempotency and reconciliation. Max 255 characters.
`first_name`	string	Yes	Payer’s first name.
`last_name`	string	Yes	Payer’s last name.
`email`	string	Yes	Payer’s email address. Must be valid email format.
`document_key`	string	Yes	Document type identifier (e.g., `IFE`, `CPF`, `SSN`). See `mandatory_fields` from Get Payment Methods.
`document_number`	string	Yes	Document number. Must match the validation regex for the selected document type.
`invoice_description`	string	Yes	Description displayed to payer on receipts and invoices. Max 500 characters.
`notification_url`	string	Yes	HTTPS webhook endpoint to receive transaction status updates. Must respond with 2xx. See Webhooks.
`redirect_url`	string	Yes	HTTPS URL where payer is redirected after payment completion (success, failure, or cancellation).
`logo`	string	No	HTTPS URL to your company logo. Displayed in hosted payment pages. Recommended size: 200x50px.
`mobile`	boolean	No	Set to `true` to optimize payment experience for mobile devices. Default: `false`.
`language`	string	No	ISO 639-1 language code (e.g., `es`, `en`, `pt`). Defaults to country’s primary language.
`fee_on_payer`	boolean	No	If `true`, payment fees are charged to the payer. If `false`, fees are deducted from your balance. Default: `false`.

Note: Required fields vary by payment_type and payment_method. Always check mandatory_fields returned by the Get Payment Methods endpoint for the specific method you’re using.

Example Requests

Credit Card Payment (Visa)

curl -X POST "https://api.cashela.com/api/v1/pay-in/deposit-creation" \
  -H "Authorization: Basic $(echo -n 'your_business_key:your_business_secret' | base64)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 8c3b9d2b-7d3a-4c60-9f5e-3c9ad9f41a2e" \
  -d '{
    "country": "MEX",
    "amount": 100.00,
    "payment_type": "CREDIT_CARD",
    "payment_method": "VI",
    "external_identifier": "ORDER-2025-00123",
    "first_name": "Alexander",
    "last_name": "Sanchez",
    "email": "alex.sanchez@example.com",
    "document_key": "IFE",
    "document_number": "SNCSCR84040225M300",
    "invoice_description": "Premium subscription - Annual plan",
    "logo": "https://yourdomain.com/logo.png",
    "notification_url": "https://yourdomain.com/webhooks/payin",
    "redirect_url": "https://yourdomain.com/payment/complete",
    "mobile": false,
    "language": "es",
    "fee_on_payer": false
  }'

Cash Voucher Payment (OXXO)

curl -X POST "https://api.cashela.com/api/v1/pay-in/deposit-creation" \
  -H "Authorization: Basic $(echo -n 'your_business_key:your_business_secret' | base64)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 2ff9a6f5-0a6b-4f40-8f0a-8e4c237a6e1a" \
  -d '{
    "country": "MEX",
    "amount": 500.00,
    "payment_type": "VOUCHER",
    "payment_method": "OXXO",
    "external_identifier": "ORDER-2025-00124",
    "first_name": "Maria",
    "last_name": "Lopez",
    "email": "maria.lopez@example.com",
    "document_key": "IFE",
    "document_number": "LPZMRA92051512H700",
    "invoice_description": "E-commerce purchase - Order #4821",
    "notification_url": "https://yourdomain.com/webhooks/payin",
    "redirect_url": "https://yourdomain.com/payment/complete",
    "language": "es",
    "fee_on_payer": true
  }'

Bank Transfer Payment (PIX - Brazil)

curl -X POST "https://api.cashela.com/api/v1/pay-in/deposit-creation" \
  -H "Authorization: Basic $(echo -n 'your_business_key:your_business_secret' | base64)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: f8a4c2d1-9e5b-4a71-b8f3-2c6d8e9a1b4f" \
  -d '{
    "country": "BRA",
    "amount": 250.00,
    "payment_type": "BANK_TRANSFER",
    "payment_method": "PIX",
    "external_identifier": "ORDER-2025-00125",
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao.silva@example.com",
    "document_key": "CPF",
    "document_number": "12345678901",
    "invoice_description": "Digital product purchase",
    "notification_url": "https://yourdomain.com/webhooks/payin",
    "redirect_url": "https://yourdomain.com/payment/complete",
    "language": "pt",
    "fee_on_payer": false
  }'

Response Format

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "payin_01HJ3K9X7M8N9P0Q1R2S3T4U5V",
    "reference": "CSH-20250202-00001234",
    "external_identifier": "ORDER-2025-00123",
    "status": "pending",
    "status_message": null,
    "created_at": "2025-02-02T10:30:00Z",
    "details": {
      "invoice_number": "INV-2025-00001234",
      "invoice_description": "Premium subscription - Annual plan",
      "invoice_country": "MEX",
      "invoice_currency": "MXN",
      "invoice_amount": 1900.00,
      "invoice_fee": 80.00,
      "net_amount": 1820.00,
      "paying": {
        "method": "CREDIT_CARD",
        "code": "VI",
        "name": "Visa",
        "logo": "https://cdn.cashela.com/payment-methods/visa.png",
        "metadata": {
          "iframe": false,
          "redirect_url": "https://checkout.payment-processor.com/session/abc123xyz",
          "digitable_line": null,
          "validity_period": "2025-02-02T23:59:59Z",
          "instructions": "Complete payment within 24 hours"
        }
      }
    }
  },
  "message": "Deposit transaction created successfully"
}

Response for Voucher Payments

For cash voucher payments (OXXO, boleto, etc.), the response includes a digitable_line:

{
  "success": true,
  "data": {
    "id": "payin_01HJ3KBCD8E9F0G1H2I3J4K5L6",
    "reference": "CSH-20250202-00001235",
    "external_identifier": "ORDER-2025-00124",
    "status": "pending",
    "status_message": "Awaiting payment at OXXO location",
    "created_at": "2025-02-02T10:35:00Z",
    "details": {
      "invoice_number": "INV-2025-00001235",
      "invoice_description": "E-commerce purchase - Order #4821",
      "invoice_country": "MEX",
      "invoice_currency": "MXN",
      "invoice_amount": 550.00,
      "invoice_fee": 50.00,
      "net_amount": 500.00,
      "paying": {
        "method": "VOUCHER",
        "code": "OXXO",
        "name": "OXXO",
        "logo": "https://cdn.cashela.com/payment-methods/oxxo.png",
        "metadata": {
          "iframe": false,
          "redirect_url": "https://yourdomain.com/payment/voucher/abc123xyz",
          "digitable_line": "9501234567890123456789012345678901234567890123",
          "validity_period": "2025-02-09T23:59:59Z",
          "instructions": "Present this code at any OXXO store to complete payment",
          "barcode_url": "https://cdn.cashela.com/vouchers/abc123xyz.png"
        }
      }
    }
  },
  "message": "Voucher generated successfully"
}

Response Parameters

Field	Type	Description
`success`	boolean	Indicates if the request was successful. Always `true` for 2xx responses.
`data.id`	string	Unique Cashela transaction identifier. Use for support inquiries.
`data.reference`	string	Cashela reference number for reconciliation and reporting.
`data.external_identifier`	string	Your original transaction reference echoed back.
`data.status`	string	Transaction status: `pending`, `processing`, `succeeded`, `failed`, `cancelled`.
`data.status_message`	string\|null	Additional context about the current status, if available.
`data.created_at`	string	ISO 8601 timestamp of transaction creation.
`data.details.invoice_number`	string	Generated invoice number for accounting purposes.
`data.details.invoice_description`	string	Invoice description from your request.
`data.details.invoice_country`	string	ISO 3-letter country code.
`data.details.invoice_currency`	string	ISO 3-letter currency code.
`data.details.invoice_amount`	number	Total amount charged including fees (when `fee_on_payer` is true).
`data.details.invoice_fee`	number	Transaction fee amount.
`data.details.net_amount`	number	Amount you receive after fees (when `fee_on_payer` is false).
`data.details.paying.method`	string	Payment method type.
`data.details.paying.code`	string	Specific payment method code.
`data.details.paying.name`	string	Human-readable payment method name.
`data.details.paying.logo`	string	URL to payment method logo image.
`data.details.paying.metadata.iframe`	boolean	If `true`, payment can be completed in an iframe.
`data.details.paying.metadata.redirect_url`	string\|null	URL to redirect user for payment completion. Required for redirect flows.
`data.details.paying.metadata.digitable_line`	string\|null	Payment code for cash vouchers (OXXO, boleto, etc.).
`data.details.paying.metadata.validity_period`	string	ISO 8601 timestamp when payment instruction expires.
`data.details.paying.metadata.instructions`	string\|null	Human-readable payment instructions for the customer.
`data.details.paying.metadata.barcode_url`	string\|null	URL to barcode image for voucher payments.
`message`	string	Human-readable success message.

Transaction Statuses

Status	Description	Next Steps
`pending`	Transaction created, awaiting payment	Redirect customer to payment page or display payment instructions
`processing`	Payment received, being processed	Wait for final status via webhook
`succeeded`	Payment completed successfully	Deliver goods/services to customer
`failed`	Payment failed or was declined	Contact customer for alternative payment method
`cancelled`	Payment cancelled by customer or expired	Create new transaction if customer wants to retry

Webhook Events

Your notification_url will receive real-time updates for the following events:

Event	When it’s sent	Action Required
`pay-in.created`	Transaction created	Informational only
`pay-in.pending`	Awaiting payment completion	Monitor for timeout
`pay-in.processing`	Payment being verified	Wait for final status
`pay-in.succeeded`	Payment completed successfully	Fulfill order
`pay-in.failed`	Payment failed	Notify customer, offer retry
`pay-in.cancelled`	Payment cancelled or expired	Clean up pending orders
`refund.created`	Refund initiated	Informational only
`refund.succeeded`	Refund completed	Update accounting
`refund.failed`	Refund failed	Contact support

Important: Always verify webhook signatures using the X-Cashela-Signature header before processing events. See Webhook Security for implementation details.

Webhook Requirements:

Must respond with HTTP 2xx status code within 10 seconds
Implement idempotent event handling (events may be delivered multiple times)
Use HTTPS endpoints only
Cashela retries failed webhooks with exponential backoff for up to 72 hours

Error Responses

All error responses follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "Additional context if applicable"
    }
  },
  "request_id": "req_01HJ3KBCD8E9F0G1H2I3J4K5L6"
}

Common Errors

HTTP Status	Error Code	Description	Resolution
400	`INVALID_INPUT`	Malformed request body or invalid JSON	Check request syntax and field types
400	`MISSING_REQUIRED_FIELD`	Required parameter is missing	Include all required fields from spec
401	`UNAUTHORIZED`	Invalid or missing credentials	Verify Basic Auth credentials are correct
403	`FORBIDDEN`	IP address not allowlisted	Add your IP to allowlist in dashboard
403	`INSUFFICIENT_BALANCE`	Not enough funds for transaction	Add funds to your business wallet
404	`PAYMENT_METHOD_NOT_FOUND`	Invalid payment method code	Use valid code from Get Payment Methods
409	`IDEMPOTENCY_CONFLICT`	Same idempotency key with different body	Use new key or send identical request
409	`DUPLICATE_TRANSACTION`	Transaction with same external_identifier exists	Use unique external_identifier per transaction
422	`VALIDATION_ERROR`	Field validation failed	Check error details for specific field issues
422	`INVALID_DOCUMENT`	Document number invalid for selected type	Verify document format matches country requirements
422	`UNSUPPORTED_COUNTRY`	Country not supported for this payment method	Choose different country or payment method
429	`RATE_LIMITED`	Too many requests	Wait and retry with exponential backoff
500	`INTERNAL_ERROR`	Server error	Retry with exponential backoff
502	`BAD_GATEWAY`	Payment provider unavailable	Retry after a few seconds
503	`SERVICE_UNAVAILABLE`	Temporary service interruption	Check status page and retry

Validation Error Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "email": "Invalid email format",
      "document_number": "Document number does not match required pattern for IFE: ^[A-Z]{4}[0-9]{6}[HM][A-Z]{5}[0-9]{2}$",
      "amount": "Amount must be greater than minimum of 10.00 MXN"
    }
  },
  "request_id": "req_01HJ3KBCD8E9F0G1H2I3J4K5L6"
}

Best Practices

Idempotency Implementation

// Generate unique idempotency key per transaction
const { v4: uuidv4 } = require('uuid');

const createDeposit = async (orderData) => {
  const idempotencyKey = uuidv4();

  try {
    const response = await fetch('https://api.cashela.com/api/v1/pay-in/deposit-creation', {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${Buffer.from(`${businessKey}:${businessSecret}`).toString('base64')}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey
      },
      body: JSON.stringify(orderData)
    });

    return await response.json();
  } catch (error) {
    // Safe to retry with same idempotency key
    console.error('Request failed, safe to retry:', error);
    throw error;
  }
};

Error Handling

import requests
import time
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_deposit_with_retry(order_data):
    # Configure retry strategy
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["POST"]
    )

    adapter = HTTPAdapter(max_retries=retry_strategy)
    session = requests.Session()
    session.mount("https://", adapter)

    try:
        response = session.post(
            'https://api.cashela.com/api/v1/pay-in/deposit-creation',
            json=order_data,
            auth=(business_key, business_secret),
            headers={
                'Content-Type': 'application/json',
                'Idempotency-Key': order_data['idempotency_key']
            },
            timeout=30
        )
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 422:
            # Handle validation errors
            error_data = e.response.json()
            print(f"Validation error: {error_data['error']['details']}")
        raise

Payment Flow Integration

// Complete payment flow example
async function initiatePayment(orderDetails: OrderDetails): Promise<PaymentResult> {
  // Step 1: Create deposit transaction
  const depositResponse = await createDeposit({
    country: orderDetails.country,
    amount: orderDetails.amount,
    payment_type: orderDetails.paymentType,
    payment_method: orderDetails.paymentMethod,
    external_identifier: orderDetails.orderId,
    // ... other required fields
  });

  if (!depositResponse.success) {
    throw new Error(`Deposit creation failed: ${depositResponse.error.message}`);
  }

  const { data } = depositResponse;

  // Step 2: Handle different payment flows
  if (data.details.paying.metadata.redirect_url) {
    // Redirect flow (most common)
    return {
      type: 'redirect',
      url: data.details.paying.metadata.redirect_url,
      transactionId: data.id
    };
  } else if (data.details.paying.metadata.digitable_line) {
    // Voucher flow (OXXO, boleto, etc.)
    return {
      type: 'voucher',
      code: data.details.paying.metadata.digitable_line,
      barcodeUrl: data.details.paying.metadata.barcode_url,
      instructions: data.details.paying.metadata.instructions,
      expiresAt: data.details.paying.metadata.validity_period,
      transactionId: data.id
    };
  }

  // Step 3: Store transaction ID for webhook reconciliation
  await storeTransactionMapping(orderDetails.orderId, data.id);

  return {
    type: 'processing',
    transactionId: data.id
  };
}

Get Countries – Query supported countries
Get Payment Methods – Discover available payment options
Get Exchange Rates – Calculate fees and FX rates
Webhooks – Implement webhook handlers
Error Handling – Complete error reference
Idempotency – Safe retry implementation
Field Validation – Input validation rules

Create Deposit Transaction

Create Deposit Transaction

Endpoint

Required Headers

Request Parameters

Body Parameters

Example Requests

Credit Card Payment (Visa)

Cash Voucher Payment (OXXO)

Bank Transfer Payment (PIX - Brazil)

Response Format

Success Response (201 Created)

Response for Voucher Payments

Response Parameters

Transaction Statuses

Webhook Events

Error Responses

Common Errors

Validation Error Example

Best Practices

Idempotency Implementation

Error Handling

Payment Flow Integration

Related Documentation