Payment Intents

Payment Intents help you manage the process of collecting payments from your customers. We recommend creating one Payment Intent per order or customer session in your system. This allows you to track the payment history for a specific session.

Throughout its lifecycle, a Payment Intent moves through various statuses as it interacts with Paytree to handle authentication steps and, ultimately, to complete a successful charge, if applicable.

Create Payment Intent

Do not send sensitive information, such as card holder data to our API. The "card" object is available for exclusive use to a limited number of customers and requires approval from our compliance team.

This method creates a new Payment Intent, which initiates the payment process for a customer, allowing you to collect payment details and manage the payment flow.

When creating a new payment intent request, you can pass the following identifiers used in callbacks to correlate our transaction with your local records.

• transaction_ref - Unique transaction reference from your system, for example, an Order ID. Any requests with a previously used transaction_ref will be rejected.

• client_ref - Unique identifier used to reference your client, this can be your customer ID or email address for example.

• notification_url - A callback url where requests will be made every time a status change is triggered.

post

Authorizations

tokenAuthjwtAuth

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

transaction_refstring · min: 1 · max: 128Required

client_refstring · min: 1 · max: 128Required

amountstring · decimalRequiredPattern: ^-?\d{0,8}(?:\.\d{0,2})?$

amount_currencystring · enumRequired

• AED - AED د.إ
• BHD - BHD .د.ب
• CAD - CAD $
• DKK - DKK kr.
• EUR - EUR €
• GBP - GBP £
• KWD - KWD د.ك
• OMR - OMR ﷼
• QAR - QAR ﷼
• SAR - SAR ﷼
• USD - USD $

Possible values:

methodall ofOptionalDefault: card

string · enumOptional

• card - Card
• crypto - Crypto
• wire - Wire
• paypal - Paypal
• klarna - Klarna
• ideal - Ideal
• bancontact - Bancontact

Possible values:

metadataanyOptional

force_routestring · uuidOptional

Responses

201

The created payment intent

application/json

post

HTTPcURLJavaScriptPython

POST /v1/transaction/payment_intent/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 599

{
  "transaction_ref": "text",
  "client_ref": "text",
  "amount": "text",
  "amount_currency": "AED",
  "method": "card",
  "card": {
    "number": "text",
    "exp_month": "text",
    "exp_year": "text",
    "cvc": "text"
  },
  "customer": {
    "first_name": "text",
    "last_name": "text",
    "email": "[email protected]",
    "phone": "text"
  },
  "address": {
    "street": "text",
    "city": "text",
    "state": "text",
    "zip": "text",
    "country": "AF"
  },
  "session": {
    "ip_address": "text",
    "user_agent": "text"
  },
  "callback": {
    "notification_url": "https://example.com",
    "return_url": "https://example.com",
    "cancel_url": "https://example.com"
  },
  "metadata": null,
  "force_route": "123e4567-e89b-12d3-a456-426614174000"
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

201

The created payment intent

{
  "id": 1,
  "client_ref": "text",
  "payment_link": "https://example.com"
}

Get all Payment Intents

This method retrieves a list of all Payment Intents in your account, providing an overview of all payment sessions and their current statuses, useful for tracking multiple payments.

get

Authorizations

tokenAuthjwtAuth

Query parameters

client_emailstringOptional

client_refstringOptional

domainstringOptional

gateway_idstringOptional

pageintegerOptional

A page number within the paginated result set.

searchstringOptional

A search term.

transaction_refstringOptional

Responses

200Success

application/json

get

HTTPcURLJavaScriptPython

GET /v1/transaction/payment_intent/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "transaction_ref": "text",
      "client_ref": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "[email protected]",
      "phone": "text",
      "address": "text",
      "amount": "text",
      "currency": "text",
      "method": "card",
      "payment_link": "text",
      "payment": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "amount": "text",
          "fee": "text",
          "refunded": "text",
          "currency": "text",
          "status": "pending",
          "refund": [
            {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "amount": "text",
              "currency": "text",
              "payment": "123e4567-e89b-12d3-a456-426614174000",
              "gateway_id": "text",
              "created": "2025-07-08T15:57:53.272Z"
            }
          ],
          "created": "2025-07-08T15:57:53.272Z"
        }
      ],
      "actions": null,
      "metadata": null,
      "created": "2025-07-08T15:57:53.272Z"
    }
  ]
}

Get Payment Intent

This method fetches detailed information about a specific Payment Intent by its unique identifier, allowing you to retrieve the latest payment status and related details for a particular payment.

get

Authorizations

tokenAuthjwtAuth

Path parameters

idstringRequired

Responses

200Success

application/json

get

HTTPcURLJavaScriptPython

GET /v1/transaction/payment_intent/{id}/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200Success

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "transaction_ref": "text",
  "client_ref": "text",
  "first_name": "text",
  "last_name": "text",
  "email": "[email protected]",
  "phone": "text",
  "address": "text",
  "amount": "text",
  "currency": "text",
  "method": "card",
  "payment_link": "text",
  "payment": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "text",
      "fee": "text",
      "refunded": "text",
      "currency": "text",
      "status": "pending",
      "refund": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "amount": "text",
          "currency": "text",
          "payment": "123e4567-e89b-12d3-a456-426614174000",
          "gateway_id": "text",
          "created": "2025-07-08T15:57:53.272Z"
        }
      ],
      "created": "2025-07-08T15:57:53.272Z"
    }
  ],
  "actions": null,
  "metadata": null,
  "created": "2025-07-08T15:57:53.272Z"
}