Payment & Operations

Payment

Within the Payment API V2 solution, the payment resource is the main resource. It is created when the client-session is SUBMITTED.
Apart from order details, which are also available in the client-session, the payment resource contains:

• Split: Breakdown of the payment across different partners.
• Amounts: Overview of the financial state of the payment.
• Overview: Categorization of amounts for each payment operation.
• Authorization: Details about the authorization status and partner transactions.

Split

The Split attribute provides a breakdown of the payment methods and amounts chosen by the client during validation.

Example

• Ingenico - Credit Card: 100€
• Illicado - Gift Card: 20€

{
    "split": [
        {
            "partner": "ingenico",
            "method": "creditcard",
            "amount": 10000
        },
        {
            "partner": "illicado",
            "method": "giftcard",
            "amount": 2000
        }
    ]
}

Amounts

The Amounts field provides a consolidated view of all financial transactions related to the payment, including captures, refunds, voids, and authorizations.

Field	Description
Total Authorized	Total amount successfully authorized for the payment.
Total Captured	Total amount that has been captured (funds transferred).
Available to Capture	Remaining amount that can still be captured.
Total Refunded	Total amount refunded to the customer.
Available to Refund	Remaining amount that can still be refunded.
Total Voided	Total amount that has been voided (authorization canceled).
Available to Void	Remaining amount that can still be voided.

Example

{
    "amounts": {
        "authorize_pending": 0,
        "total_authorized": 4200,
        "total_captured": 4200,
        "available_to_capture": 0,
        "total_refunded": 0,
        "available_to_refund": 4200,
        "total_voided": 0,
        "available_to_void": 0
    }
}

Overview

The Overview field helps merchants understand what has been done on the payment.

Possible states:

• NOT: No action has been performed.
• PARTIALLY: A portion of the amount has been used.
• TOTALLY: The full amount has been processed.

Example

{
    "overview": {
        "consumed": "TOTALLY",
        "captured": "TOTALLY",
        "voided": "NOT",
        "refunded": "NOT"
    }
}

Payment Operations

A payment operation refers to a financial action executed on a payment transaction. Merchants can use the API to dynamically manage payments through.

Capture

Finalizes a payment by transferring the authorized amount to the merchant.

Endpoint

• Endpoint: /payment/v2/payments/{payment_id}/captures
• Method: POST
• See Capture reference

Successful Capture Response

Response Data

Response body for a full capture operation.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "overview": {
    "consumed": "NOT",
    "captured": "NOT",
    "voided": "NOT",
    "refunded": "NOT"
  },
  "client_session_id": "083e320e-e2e2-4a94-b5e1-abc028b960ab",
  "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  "version": 3,
  "order_reference": "order_01",
  "amount": 4299,
  "currency": "EUR",
  "capture_mode": "MANUAL",
  "captures": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "voids": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "refunds": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "authorization": {
    "updated_at": "2019-08-24T14:15:22Z",
    "status": "AUTHORIZED",
    "partner_transactions": [
      {
        "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "amount": 4299,
        "partner": "ingenico",
        "method": "creditcard",
        "partner_reference": "AE0002ZCF7652QFF",
        "partner_status": "000.000.000",
        "partner_status_description": "Transaction succeeded",
        "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
        "status": "AUTHORIZED",
        "card": {
          "bin": "513842",
          "last_four_digits": "1234",
          "holder_name": "John Doe",
          "expiry_month": "01",
          "expiry_year": "24",
          "selected_network": "VISA",
          "three_ds": {
            "eci": "01",
            "version": "2.2.0",
            "flow": "CHALLENGE",
            "ds_transaction_id": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
            "acs_transaction_id": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95"
          }
        },
        "remaining_amount": 4299
      }
    ]
  },
  "amounts": {
    "total_authorized": 4299,
    "total_voided": 299,
    "available_to_void": 1000,
    "total_captured": 3000,
    "available_to_capture": 1000,
    "total_refunded": 0,
    "available_to_refund": 3000
  },
  "links": {
    "self": {
      "href": "/v2/client-sessions/9a14962c-bdcf-49d1-8673-e75dfb48013f",
      "method": "GET"
    },
    "capture": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/captures",
      "method": "POST"
    },
    "refund": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/refunds",
      "method": "POST"
    },
    "void": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/voids",
      "method": "POST"
    }
  },
  "split": [
    {
      "partner": "ingenico",
      "method": "creditcard",
      "amount": 4299,
      "parent_partner_transaction_id": "1a2b3c4d-1a2b-abcd-1234-123456789abc",
      "parent_payment_id": "9399c938-80e1-11ef-9de7-327d4a6ae82c",
      "parent_partner_token": "64837-39372-32188",
      "parent_partner_reference": 123456789
    }
  ],
  "webhook": {
    "url": "https://www.example.org/payment-hook?order_id=123456789",
    "headers": [
      {
        "name": "x-order-id",
        "values": [
          123456789
        ]
      }
    ]
  }
}

Refund

Returns all or part of the captured amount to the customer.

Endpoint

• Endpoint: /payment/v2/payments/{payment_id}/refunds
• Method: POST
• See Refund reference

Successful Refund Response

Response Data

Response body for a full refund operation.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "overview": {
    "consumed": "NOT",
    "captured": "NOT",
    "voided": "NOT",
    "refunded": "NOT"
  },
  "client_session_id": "083e320e-e2e2-4a94-b5e1-abc028b960ab",
  "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  "version": 3,
  "order_reference": "order_01",
  "amount": 4299,
  "currency": "EUR",
  "capture_mode": "MANUAL",
  "captures": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "voids": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "refunds": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "authorization": {
    "updated_at": "2019-08-24T14:15:22Z",
    "status": "AUTHORIZED",
    "partner_transactions": [
      {
        "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "amount": 4299,
        "partner": "ingenico",
        "method": "creditcard",
        "partner_reference": "AE0002ZCF7652QFF",
        "partner_status": "000.000.000",
        "partner_status_description": "Transaction succeeded",
        "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
        "status": "AUTHORIZED",
        "card": {
          "bin": "513842",
          "last_four_digits": "1234",
          "holder_name": "John Doe",
          "expiry_month": "01",
          "expiry_year": "24",
          "selected_network": "VISA",
          "three_ds": {
            "eci": "01",
            "version": "2.2.0",
            "flow": "CHALLENGE",
            "ds_transaction_id": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
            "acs_transaction_id": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95"
          }
        },
        "remaining_amount": 4299
      }
    ]
  },
  "amounts": {
    "total_authorized": 4299,
    "total_voided": 299,
    "available_to_void": 1000,
    "total_captured": 3000,
    "available_to_capture": 1000,
    "total_refunded": 0,
    "available_to_refund": 3000
  },
  "links": {
    "self": {
      "href": "/v2/client-sessions/9a14962c-bdcf-49d1-8673-e75dfb48013f",
      "method": "GET"
    },
    "capture": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/captures",
      "method": "POST"
    },
    "refund": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/refunds",
      "method": "POST"
    },
    "void": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/voids",
      "method": "POST"
    }
  },
  "split": [
    {
      "partner": "ingenico",
      "method": "creditcard",
      "amount": 4299,
      "parent_partner_transaction_id": "1a2b3c4d-1a2b-abcd-1234-123456789abc",
      "parent_payment_id": "9399c938-80e1-11ef-9de7-327d4a6ae82c",
      "parent_partner_token": "64837-39372-32188",
      "parent_partner_reference": 123456789
    }
  ],
  "webhook": {
    "url": "https://www.example.org/payment-hook?order_id=123456789",
    "headers": [
      {
        "name": "x-order-id",
        "values": [
          123456789
        ]
      }
    ]
  }
}

Void

Cancels an authorization before funds are captured.

Endpoint

• Endpoint: /payment/v2/payments/{payment_id}/voids
• Method: POST
• See Void reference

Successful Void Response

Response Data

Response body for a full void operation.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "overview": {
    "consumed": "NOT",
    "captured": "NOT",
    "voided": "NOT",
    "refunded": "NOT"
  },
  "client_session_id": "083e320e-e2e2-4a94-b5e1-abc028b960ab",
  "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  "version": 3,
  "order_reference": "order_01",
  "amount": 4299,
  "currency": "EUR",
  "capture_mode": "MANUAL",
  "captures": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "voids": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "refunds": [
    {
      "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
      "amount": 4299,
      "created_at": "2020-08-25T10:42:59.123+02:00",
      "updated_at": "2020-08-25T10:42:59.123+02:00",
      "triggered_by": "MERCHANT",
      "merchant_reference": "CAP#1223445",
      "status": "SUCCESS",
      "partner_transactions": [
        {
          "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "amount": 4299,
          "partner": "ingenico",
          "method": "creditcard",
          "partner_reference": "AE0002ZCF7652QFF",
          "partner_status": "000.000.000",
          "partner_status_description": "Transaction succeeded",
          "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
          "status": "SUCCESS",
          "remaining_amount": 4299
        }
      ],
      "order": {
        "shipments": [
          {
            "net_amount": 4299,
            "item_lines": [
              {
                "type": "PHYSICAL",
                "sku_reference": "SKU_01",
                "name": "My awesome product",
                "brand": "My awesome brand",
                "unit_gross_price": 1099,
                "net_amount": 4299,
                "discount_amount": 0,
                "quantity": 4,
                "tax_amount": 399,
                "tax_rate": 20,
                "seller_reference": "SELLER_01",
                "seller_name": "My awesome seller",
                "is_marketplace_seller": true
              }
            ]
          }
        ]
      }
    }
  ],
  "authorization": {
    "updated_at": "2019-08-24T14:15:22Z",
    "status": "AUTHORIZED",
    "partner_transactions": [
      {
        "id": "e3a6516b-0ec4-4a5b-92b0-7bb9693e82c1",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "amount": 4299,
        "partner": "ingenico",
        "method": "creditcard",
        "partner_reference": "AE0002ZCF7652QFF",
        "partner_status": "000.000.000",
        "partner_status_description": "Transaction succeeded",
        "partner_token": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
        "status": "AUTHORIZED",
        "card": {
          "bin": "513842",
          "last_four_digits": "1234",
          "holder_name": "John Doe",
          "expiry_month": "01",
          "expiry_year": "24",
          "selected_network": "VISA",
          "three_ds": {
            "eci": "01",
            "version": "2.2.0",
            "flow": "CHALLENGE",
            "ds_transaction_id": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95",
            "acs_transaction_id": "f8a333e9-cdc2-45d1-b9e5-dba95e00fa95"
          }
        },
        "remaining_amount": 4299
      }
    ]
  },
  "amounts": {
    "total_authorized": 4299,
    "total_voided": 299,
    "available_to_void": 1000,
    "total_captured": 3000,
    "available_to_capture": 1000,
    "total_refunded": 0,
    "available_to_refund": 3000
  },
  "links": {
    "self": {
      "href": "/v2/client-sessions/9a14962c-bdcf-49d1-8673-e75dfb48013f",
      "method": "GET"
    },
    "capture": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/captures",
      "method": "POST"
    },
    "refund": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/refunds",
      "method": "POST"
    },
    "void": {
      "href": "/v2/payments/9a14962c-bdcf-49d1-8673-e75dfb48013f/voids",
      "method": "POST"
    }
  },
  "split": [
    {
      "partner": "ingenico",
      "method": "creditcard",
      "amount": 4299,
      "parent_partner_transaction_id": "1a2b3c4d-1a2b-abcd-1234-123456789abc",
      "parent_payment_id": "9399c938-80e1-11ef-9de7-327d4a6ae82c",
      "parent_partner_token": "64837-39372-32188",
      "parent_partner_reference": 123456789
    }
  ],
  "webhook": {
    "url": "https://www.example.org/payment-hook?order_id=123456789",
    "headers": [
      {
        "name": "x-order-id",
        "values": [
          123456789
        ]
      }
    ]
  }
}

Default Processing Order

caution

For Capture Operations :

1. Gift card methods are processed first.
2. Other payment solutions follow.

For Refund Operations :

1. Credit card methods are processed first.
2. Other payment solutions follow.

We allow the merchant to customize this behaviour by setting a priority list in their operation requests.

Example: Processing Priority

[
    { "partner": "*", "method": "creditcard" },
    { "partner": "*", "method": "*" },
    { "partner": "illicado", "method": "*" }
]

In this example, we process first all the remaining transactions that is a creditcard method. Using the wildcards in the solution attributes allow the merchant to be generic about the partner or the method.

When the merchant decide to use the wildcards in both partner and method, we gather all the remaining transactions that have a solution that doesn't match one of the solutions that are set in the priority list.

With those operation priorities, the illicado partner payment method will be processed last.

Operation statuses

Each payment operation has a status :

Status	Description	Temporary status ?
SUCCESS	The operation was successfully completed.	No
PENDING	The final status from all partners is not yet available.	Yes Can evolve to SUCCESSor FAILURE
FAILURE	A technical error occurred during the operation.	No
CONFLICT	Some transactions succeeded while others failed.	No
UNCERTAIN	The PSP response attempts were unsatisfactory or unknown.	Yes Can evolve to SUCCESSor FAILURE

HATEOAS Links

HATEOAS links enable navigation and execution of payment operations.

Operation	Description	Condition	Method	API Link
Get Payment	Retrieve the current payment resource.	A SUBMITTED Client-Session	GET	API Reference
Capture	Execute a capture action.	Must have available funds to capture.	POST	API Reference
Void	Execute a void action.	Must have available funds to void.	POST	API Reference
Refund	Execute a refund action.	Must have available funds to refund.	POST	API Reference

Now you're ready to execute payment operations with the Purse Payment API !

Summary of the Payment Flow

1️⃣ Retrieve an Access Token (/oauth/token)
2️⃣ Create a Client Session (/payment/v2/client-sessions)
3️⃣ Integrate the Checkout Widget (widget.js_url + widget.data)
4️⃣ Handle Shopper Redirection (purse-redirection-data)
5️⃣ Perform Payment Operations (capture, void, refund)

Going further : Webhooks & Real-Time Notifications

Now that you know how to manage payment operations, how can you stay informed when a payment status changes? Instead of polling the API repeatedly, Webhooks allow you to receive real-time notifications whenever a relevant event occurs.

In the next section, we will cover:

• How webhooks work and why they are essential for automating your payment workflow.
• Available webhook status (e.g., authorization updates, capture confirmations, refunds).
• How to configure and secure webhooks to ensure reliable event handling.