Welcome to the CashPay API! This guide will walk you through the core concepts to get you up and running. We use a modern, secure flow with API calls and webhooks for reliable server-to-server confirmation.

Authentication

The CashPay API uses Bearer Tokens for authentication. You must include an Authorization header with every request.

Authorization: Bearer YOUR_API_TOKEN

Note: API tokens are valid for 55 minutes.

Core Workflow

The payment process is designed to be secure and straightforward:

1. **Create a Charge:** Your server sends a request to the CashPay API to create a charge. See the **Create a Charge** endpoint for full details.
2. **Redirect the Customer:** The API responds with a `transaction_url` for the customer to complete payment.
3. **Handle Customer Return:** After payment, CashPay redirects the customer's browser back to your specified `redirect_url`.
4. **Receive Webhook Confirmation:** Simultaneously, CashPay sends a secure POST request (a webhook) to your `post_url`. **This is the source of truth for fulfilling the order.**

The Charge Object

The charge is the central object in the CashPay API. It represents a single payment transaction and contains all the information about its state. Below is an example of a charge object after it has been successfully created.

{
  "id": "chg_a1b2c3d4e5",
  "status": "INITIATED",
  "amount": 2000,
  "currency": "YER",
  "description": "Purchase of a watch",
  "transaction_url": "https://pay.cashpay.com/session/...",
  "created": 1672531200
}

Key Attributes

• **id** (string): Unique identifier for the charge, prefixed with `chg_`.
• **status** (string): Current status: `INITIATED`, `CAPTURED`, `FAILED`.
• **amount** (integer): The transaction amount.
• **currency** (string): Three-letter ISO currency code.
• **transaction_url** (string): The secure URL you must redirect your customer to so they can complete the payment.
• **created** (timestamp): The time the charge was created.