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

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

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 د.إ
• AUD - AUD $
• BHD - BHD .د.ب
• CAD - CAD $
• CLP - CLP $
• DKK - DKK kr.
• EUR - EUR €
• GBP - GBP £
• HKD - HKD $
• KWD - KWD د.ك
• NOK - NOK kr
• NZD - NZD $
• OMR - OMR ﷼
• PLN - PLN zł
• QAR - QAR ﷼
• SAR - SAR ﷼
• SEK - SEK kr
• USD - USD $

Possible values:

methodall ofOptionalDefault: card

string · enumOptional

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

Possible values:

metadataanyOptional

force_routestring · uuidOptional

Responses

201

The created payment intent

application/json

post

/v1/transaction/payment_intent/

HTTPcURLJavaScriptPython

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

{
  "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": "[e-mail]",
    "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",
  "order_items": [
    {
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unit_price": "text",
      "sku": "text"
    }
  ]
}

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

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Query parameters

client_emailstringOptional

client_refstringOptional

domainstringOptional

gateway_idstringOptional

pageintegerOptional

A page number within the paginated result set.

route_idstringOptional

Filter by routing rule UUID used for the payment intent

searchstringOptional

A search term.

transaction_refstringOptional

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2

get

/v1/transaction/payment_intent/

HTTPcURLJavaScriptPython

GET /v1/transaction/payment_intent/ HTTP/1.1
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": "[e-mail]",
      "phone": "text",
      "address": "text",
      "amount": "text",
      "currency": "text",
      "base_amount": "text",
      "base_currency": "text",
      "method": "card",
      "payment_link": "text",
      "payment": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "amount": "text",
          "currency": "text",
          "base_amount": "text",
          "base_currency": "text",
          "fee": "text",
          "refunded": "text",
          "status": "pending",
          "refund": [
            {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "amount": "text",
              "currency": "text",
              "payment": "123e4567-e89b-12d3-a456-426614174000",
              "gateway_id": "text",
              "created": "2026-03-02T17:01:55.318Z"
            }
          ],
          "created": "2026-03-02T17:01:55.318Z"
        }
      ],
      "actions": null,
      "metadata": null,
      "order_items": null,
      "route_id": "text",
      "created": "2026-03-02T17:01:55.318Z"
    }
  ]
}

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

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idstringRequired

Responses

200Success

application/json

idstring · uuidRead-onlyRequired

transaction_refstring · max: 255Required

client_refstring · max: 255Required

first_namestring · max: 255 · nullableOptional

last_namestring · max: 255 · nullableOptional

emailstring · email · max: 254 · nullableOptional

phonestring · max: 32 · nullableOptional

addressstringRead-onlyRequired

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

currencystringRead-onlyRequired

base_amountstring · decimalOptionalPattern: ^-?\d{0,6}(?:\.\d{0,2})?$

base_currencystringRead-onlyRequired

methodstring · enumOptional

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

Possible values:

payment_linkstringRead-onlyRequired

actionsanyOptional

metadataanyOptional

order_itemsanyOptional

List of order items with name, description, quantity, unit_price, and sku

route_idstringRead-onlyRequired

createdstring · date-timeRead-onlyRequired

get

/v1/transaction/payment_intent/{id}/

HTTPcURLJavaScriptPython

GET /v1/transaction/payment_intent/{id}/ HTTP/1.1
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": "[e-mail]",
  "phone": "text",
  "address": "text",
  "amount": "text",
  "currency": "text",
  "base_amount": "text",
  "base_currency": "text",
  "method": "card",
  "payment_link": "text",
  "payment": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "amount": "text",
      "currency": "text",
      "base_amount": "text",
      "base_currency": "text",
      "fee": "text",
      "refunded": "text",
      "status": "pending",
      "refund": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "amount": "text",
          "currency": "text",
          "payment": "123e4567-e89b-12d3-a456-426614174000",
          "gateway_id": "text",
          "created": "2026-03-02T17:01:55.318Z"
        }
      ],
      "created": "2026-03-02T17:01:55.318Z"
    }
  ],
  "actions": null,
  "metadata": null,
  "order_items": null,
  "route_id": "text",
  "created": "2026-03-02T17:01:55.318Z"
}