# API reference

REST API reference for Peach Payments Orchestration. This is the markdown view of the interactive API playground.

- Interactive playground: https://playground.peachpayments.com/playground
- Complete machine-readable spec (OpenAPI): https://playground.peachpayments.com/openapi.json
- Base URL: `https://app.sandbox-next.peachpayments.com/api`
- Authentication: send your merchant secret key in the `api-key` request header.

## Payments

### Create Payment — `POST /payments`

Create a new payment intent

Example — Simple Payment: Basic one-time payment with automatic capture

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "automatic",
  "authentication_type": "no_three_ds",
  "description": "Simple payment",
  "return_url": "https://example.com/complete"
}
```

Example — Pre-authorisation: Authorise now, capture later

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "manual",
  "authentication_type": "three_ds",
  "description": "Pre-authorised payment",
  "return_url": "https://example.com/complete"
}
```

Example — Save Card (On-Session): Save card for future on-session payments

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "setup_future_usage": "on_session",
  "customer_id": "{{customer_id}}",
  "description": "Payment with card saving",
  "return_url": "https://example.com/complete"
}
```

Example — Save Card (Off-Session): Save card for merchant-initiated payments

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "setup_future_usage": "off_session",
  "customer_id": "{{customer_id}}",
  "description": "Payment with off-session card saving",
  "return_url": "https://example.com/complete"
}
```

Example — Recurring Mandate: Set up a recurring payment mandate

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "setup_future_usage": "off_session",
  "customer_id": "{{customer_id}}",
  "mandate_data": {
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2026-07-23T20:45:51.074Z",
      "online": {
        "ip_address": "127.0.0.1",
        "user_agent": "Mozilla/5.0"
      }
    },
    "mandate_type": {
      "multi_use": {
        "amount": 100000,
        "currency": "ZAR"
      }
    }
  },
  "description": "Recurring mandate setup",
  "return_url": "https://example.com/complete"
}
```

Example — Off-Session Charge: Charge a saved payment method without customer present

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": true,
  "off_session": true,
  "customer_id": "{{customer_id}}",
  "payment_method_id": "{{payment_method_id}}",
  "description": "Off-session charge",
  "return_url": "https://example.com/complete"
}
```

Example — Mandate Charge: Charge using an existing mandate

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": true,
  "off_session": true,
  "mandate_id": "{{mandate_id}}",
  "recurring_details": {
    "type": "mandate_id",
    "data": "{{mandate_id}}"
  },
  "description": "Recurring mandate charge",
  "return_url": "https://example.com/complete"
}
```

### Retrieve Payment — `GET /payments/{payment_id}`

Retrieve details of an existing payment

Path parameters: `payment_id`

### Update Payment — `POST /payments/{payment_id}`

Update a payment before confirmation

Path parameters: `payment_id`

Request body:

```json
{
  "amount": 7500,
  "description": "Updated payment description"
}
```

### Confirm Payment — `POST /payments/{payment_id}/confirm`

Confirm a payment intent

Path parameters: `payment_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### Capture Payment — `POST /payments/{payment_id}/capture`

Capture an authorised payment

Path parameters: `payment_id`

Request body:

```json
{
  "amount_to_capture": 6500
}
```

### Cancel Payment — `POST /payments/{payment_id}/cancel`

Cancel a payment intent

Path parameters: `payment_id`

Request body:

```json
{
  "cancellation_reason": "requested_by_customer"
}
```

### List Payments — `GET /payments/list`

List all payments with optional filters

### Cancel Post Capture — `POST /payments/{payment_id}/cancel_post_capture`

Cancel/void a payment after capture

Path parameters: `payment_id`

Request body:

```json
{
  "cancellation_reason": "requested_by_customer"
}
```

### Extend Authorisation — `POST /payments/{payment_id}/extend_authorization`

Extend the authorisation period for a payment

Path parameters: `payment_id`

Request body:

```json
{}
```

### Incremental Authorisation — `POST /payments/{payment_id}/incremental_authorization`

Increment the authorised amount for a payment

Path parameters: `payment_id`

Request body:

```json
{
  "amount": 8000
}
```

### Complete Authorise — `POST /payments/{payment_id}/complete_authorise`

Complete authorisation after external authentication

Path parameters: `payment_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### Create Session Tokens — `POST /payments/session_tokens`

Create session tokens for wallet payments (Apple Pay, Google Pay)

Request body:

```json
{
  "payment_id": "{{payment_id}}",
  "wallets": [
    "apple_pay",
    "google_pay"
  ]
}
```

### Post Session Tokens — `POST /payments/{payment_id}/post_session_tokens`

Create post-session tokens for a payment

Path parameters: `payment_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### 3DS Authentication — `POST /payments/{payment_id}/3ds/authentication`

Initiate external 3DS authentication

Path parameters: `payment_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}",
  "device_channel": "BRW",
  "threeds_method_comp_ind": "Y"
}
```

### Update Metadata — `POST /payments/{payment_id}/update_metadata`

Update payment metadata

Path parameters: `payment_id`

Request body:

```json
{
  "metadata": {
    "order_id": "ORD-12345",
    "custom_field": "value"
  }
}
```

### Submit Eligibility — `POST /payments/{payment_id}/eligibility`

Submit eligibility data for a payment

Path parameters: `payment_id`

Request body:

```json
{
  "payment_method": "card"
}
```

## Payment Links

### Retrieve Payment Link — `GET /payment_link/{payment_link_id}`

Retrieve details of a payment link

Path parameters: `payment_link_id`

## Refunds

### Create Refund — `POST /refunds`

Create a refund for a payment

Request body:

```json
{
  "payment_id": "{{payment_id}}",
  "amount": 6500,
  "reason": "Customer requested refund"
}
```

### Retrieve Refund — `GET /refunds/{refund_id}`

Retrieve refund details

Path parameters: `refund_id`

### Update Refund — `POST /refunds/{refund_id}`

Update refund details

Path parameters: `refund_id`

Request body:

```json
{
  "reason": "Updated refund reason",
  "metadata": {
    "updated_by": "merchant"
  }
}
```

### List Refunds — `POST /refunds/list`

List refunds with filters

Request body:

```json
{
  "payment_id": "{{payment_id}}"
}
```

## Customers

### Create Customer — `POST /customers`

Create a new customer

Request body:

```json
{
  "email": "customer@example.com",
  "name": "Test Customer",
  "phone": "+27123456789",
  "description": "Playground test customer"
}
```

### Retrieve Customer — `GET /customers/{customer_id}`

Retrieve customer details

Path parameters: `customer_id`

### Update Customer — `POST /customers/{customer_id}`

Update customer details

Path parameters: `customer_id`

Request body:

```json
{
  "name": "Updated Customer Name",
  "email": "updated@example.com"
}
```

### Delete Customer — `DELETE /customers/{customer_id}`

Delete a customer

Path parameters: `customer_id`

### List Customers — `GET /customers/list`

List all customers

## Mandates

### Retrieve Mandate — `GET /mandates/{mandate_id}`

Retrieve mandate details

Path parameters: `mandate_id`

### Revoke Mandate — `POST /mandates/revoke/{mandate_id}`

Revoke an active mandate

Path parameters: `mandate_id`

Request body:

```json
{}
```

### List Customer Mandates — `GET /customers/{customer_id}/mandates`

List all mandates for a customer

Path parameters: `customer_id`

## Payment Methods

### Create Payment Method — `POST /payment_methods`

Create a new payment method

Request body:

```json
{
  "payment_method": "card",
  "payment_method_type": "credit",
  "customer_id": "{{customer_id}}"
}
```

### Retrieve Payment Method — `GET /payment_methods/{method_id}`

Retrieve payment method details

Path parameters: `method_id`

### Update Payment Method — `POST /payment_methods/{method_id}/update`

Update a payment method

Path parameters: `method_id`

Request body:

```json
{
  "card_holder_name": "Updated Name"
}
```

### Delete Payment Method — `DELETE /payment_methods/{method_id}`

Delete a payment method

Path parameters: `method_id`

### List Customer Payment Methods — `GET /customers/{customer_id}/payment_methods`

List saved payment methods for a customer

Path parameters: `customer_id`

### List Merchant Payment Methods — `GET /account/payment_methods`

List payment methods available for a merchant

### List Payment Methods for Payment — `GET /customers/payment_methods`

List customer saved payment methods for a payment

### Set Default Payment Method — `POST /{customer_id}/payment_methods/{payment_method_id}/default`

Set default payment method for a customer

Path parameters: `customer_id`, `payment_method_id`

Request body:

```json
{}
```

## Disputes

### Retrieve Dispute — `GET /disputes/{dispute_id}`

Retrieve dispute details

Path parameters: `dispute_id`

### List Disputes — `GET /disputes/list`

List all disputes

## Payouts

### Create Payout — `POST /payouts/create`

Create a new payout

Request body:

```json
{
  "amount": 10000,
  "currency": "ZAR",
  "customer_id": "{{customer_id}}",
  "payout_type": "bank"
}
```

### Retrieve Payout — `GET /payouts/{payout_id}`

Retrieve payout details

Path parameters: `payout_id`

### Update Payout — `POST /payouts/{payout_id}`

Update a payout

Path parameters: `payout_id`

Request body:

```json
{
  "description": "Updated payout description"
}
```

### Confirm Payout — `POST /payouts/{payout_id}/confirm`

Confirm a payout

Path parameters: `payout_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### Fulfill Payout — `POST /payouts/{payout_id}/fulfill`

Fulfill a payout

Path parameters: `payout_id`

Request body:

```json
{
  "payout_method_data": {
    "bank": {
      "bank_account_number": "123456789"
    }
  }
}
```

### Cancel Payout — `POST /payouts/{payout_id}/cancel`

Cancel a payout

Path parameters: `payout_id`

Request body:

```json
{
  "cancellation_reason": "merchant_request"
}
```

### List Payouts — `GET /payouts/list`

List all payouts

### List Payouts with Filters — `POST /payouts/list`

List payouts with filters

Request body:

```json
{
  "customer_id": "{{customer_id}}"
}
```

### List Available Filters — `POST /payouts/filter`

List available payout filters

Request body:

```json
{
  "connector": [
    "wise"
  ],
  "currency": [
    "ZAR"
  ]
}
```

## Routing

### Create Routing Config — `POST /routing`

Create a new routing configuration

Request body:

```json
{
  "name": "My Routing Config",
  "description": "Custom routing rules",
  "algorithm": {
    "type": "single",
    "data": {
      "connector": "stripe"
    }
  }
}
```

### List Routing Configs — `GET /routing`

List all routing configurations

### Retrieve Routing Config — `GET /routing/{routing_algorithm_id}`

Retrieve routing configuration details

Path parameters: `routing_algorithm_id`

### Activate Routing Config — `POST /routing/{routing_algorithm_id}/activate`

Activate a routing configuration

Path parameters: `routing_algorithm_id`

Request body:

```json
{}
```

### Deactivate Routing — `POST /routing/deactivate`

Deactivate current routing configuration

Request body:

```json
{
  "routing_type": "payment_routing"
}
```

### Retrieve Default Config — `GET /routing/default`

Retrieve default routing configuration

### Update Default Config — `POST /routing/default`

Update default routing configuration

Request body:

```json
[
  {
    "connector": "stripe",
    "merchant_connector_id": "{{merchant_connector_id}}"
  }
]
```

### Retrieve Active Config — `GET /routing/active`

Retrieve currently active routing configuration

### Retrieve Default for Profile — `GET /routing/default/profile`

Retrieve default routing for a profile

### Update Default for Profile — `POST /routing/default/profile/{profile_id}`

Update default routing for a profile

Path parameters: `profile_id`

Request body:

```json
[
  {
    "connector": "stripe",
    "merchant_connector_id": "{{merchant_connector_id}}"
  }
]
```

### Evaluate Routing — `POST /routing/evaluate`

Evaluate routing for a payment

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "payment_method": "card"
}
```

### Routing Feedback — `POST /routing/feedback`

Provide feedback for routing

Request body:

```json
{
  "payment_id": "{{payment_id}}",
  "choice": [
    {
      "connector": "stripe"
    }
  ]
}
```

### Evaluate Routing Rule — `POST /routing/rule/evaluate`

Evaluate a specific routing rule

Request body:

```json
{
  "name": "Test Rule",
  "algorithm": {
    "type": "single",
    "data": {
      "connector": "stripe"
    }
  }
}
```

### Update Success-Based Config — `PATCH /account/{account_id}/business_profile/{profile_id}/dynamic_routing/success_based/config/{algorithm_id}`

Update success-based dynamic routing config for profile

Path parameters: `account_id`, `profile_id`, `algorithm_id`

Request body:

```json
{}
```

### Toggle Success-Based Routing — `POST /account/{account_id}/business_profile/{profile_id}/dynamic_routing/success_based/toggle`

Toggle success-based dynamic routing for profile

Path parameters: `account_id`, `profile_id`

Request body:

```json
{
  "enable": true
}
```

### Toggle Elimination Routing — `POST /account/{account_id}/business_profile/{profile_id}/dynamic_routing/elimination/toggle`

Toggle elimination routing for profile

Path parameters: `account_id`, `profile_id`

Request body:

```json
{
  "enable": true
}
```

### Create Success-Based Routing — `POST /account/{account_id}/business_profile/{profile_id}/dynamic_routing/success_based/create`

Create auth rate based dynamic routing

Path parameters: `account_id`, `profile_id`

Request body:

```json
{}
```

### Create Elimination Routing — `POST /account/{account_id}/business_profile/{profile_id}/dynamic_routing/elimination/create`

Create elimination routing

Path parameters: `account_id`, `profile_id`

Request body:

```json
{}
```

### Toggle Contract Routing — `POST /account/{account_id}/business_profile/{profile_id}/dynamic_routing/contracts/toggle`

Toggle contract routing for profile

Path parameters: `account_id`, `profile_id`

Request body:

```json
{
  "enable": true
}
```

### Update Contract Routing Config — `PATCH /account/{account_id}/business_profile/{profile_id}/dynamic_routing/contracts/config/{algorithm_id}`

Update contract-based dynamic routing config for profile

Path parameters: `account_id`, `profile_id`, `algorithm_id`

Request body:

```json
{}
```

## Merchant Account

### Create Merchant Account — `POST /accounts`

Create a new merchant account

Request body:

```json
{
  "merchant_name": "Test Merchant"
}
```

### Retrieve Merchant Account — `GET /accounts/{account_id}`

Retrieve merchant account details

Path parameters: `account_id`

### Update Merchant Account — `POST /accounts/{account_id}`

Update merchant account

Path parameters: `account_id`

Request body:

```json
{
  "merchant_name": "Updated Merchant Name"
}
```

### Delete Merchant Account — `DELETE /accounts/{account_id}`

Delete a merchant account

Path parameters: `account_id`

### Toggle KV Status — `POST /accounts/{account_id}/kv`

Enable/disable KV for merchant account

Path parameters: `account_id`

Request body:

```json
{
  "kv_enabled": true
}
```

## Merchant Connector

### Create Connector — `POST /account/{account_id}/connectors`

Create a new merchant connector

Path parameters: `account_id`

Request body:

```json
{
  "connector_type": "payment_processor",
  "connector_name": "stripe",
  "connector_account_details": {}
}
```

### List Connectors — `GET /account/{account_id}/connectors`

List all merchant connectors

Path parameters: `account_id`

### Retrieve Connector — `GET /account/{account_id}/connectors/{merchant_connector_id}`

Retrieve connector details

Path parameters: `account_id`, `merchant_connector_id`

### Update Connector — `POST /account/{account_id}/connectors/{merchant_connector_id}`

Update a merchant connector

Path parameters: `account_id`, `merchant_connector_id`

Request body:

```json
{
  "status": "active"
}
```

### Delete Connector — `DELETE /account/{account_id}/connectors/{merchant_connector_id}`

Delete a merchant connector

Path parameters: `account_id`, `merchant_connector_id`

## Business Profile

### Create Business Profile — `POST /account/{account_id}/business_profile`

Create a new business profile

Path parameters: `account_id`

Request body:

```json
{
  "profile_name": "Default Profile"
}
```

### List Business Profiles — `GET /account/{account_id}/business_profile`

List all business profiles

Path parameters: `account_id`

### Retrieve Business Profile — `GET /account/{account_id}/business_profile/{profile_id}`

Retrieve business profile details

Path parameters: `account_id`, `profile_id`

### Update Business Profile — `POST /account/{account_id}/business_profile/{profile_id}`

Update a business profile

Path parameters: `account_id`, `profile_id`

Request body:

```json
{
  "profile_name": "Updated Profile"
}
```

### Delete Business Profile — `DELETE /account/{account_id}/business_profile/{profile_id}`

Delete a business profile

Path parameters: `account_id`, `profile_id`

## API Keys

### Create API Key — `POST /api_keys/{merchant_id}`

Create a new API key

Path parameters: `merchant_id`

Request body:

```json
{
  "name": "Production API Key",
  "description": "API key for production environment"
}
```

### Retrieve API Key — `GET /api_keys/{merchant_id}/{key_id}`

Retrieve API key details

Path parameters: `merchant_id`, `key_id`

### Update API Key — `POST /api_keys/{merchant_id}/{key_id}`

Update an API key

Path parameters: `merchant_id`, `key_id`

Request body:

```json
{
  "name": "Updated API Key Name"
}
```

### Revoke API Key — `DELETE /api_keys/{merchant_id}/{key_id}`

Revoke an API key

Path parameters: `merchant_id`, `key_id`

### List API Keys — `GET /api_keys/{merchant_id}/list`

List all API keys for a merchant

Path parameters: `merchant_id`

## Blocklist

### Add to Blocklist — `POST /blocklist`

Add an entry to the merchant blocklist. Payments matching a blocked card BIN, extended card BIN, or payment-method fingerprint are rejected before reaching a connector (while the blocklist guard is enabled).

Example — Block Card BIN: Block all cards sharing a 6-digit BIN

```json
{
  "type": "card_bin",
  "data": "424242"
}
```

Example — Block Extended Card BIN: Block cards sharing an 8-digit extended BIN

```json
{
  "type": "extended_card_bin",
  "data": "42424242"
}
```

Example — Block Fingerprint: Block a specific tokenised payment-method fingerprint

```json
{
  "type": "fingerprint",
  "data": "{{fingerprint_id}}"
}
```

### List Blocklist — `GET /blocklist`

List active blocklist entries of a given kind. Requires a `data_kind` query parameter (`card_bin`, `extended_card_bin`, or `payment_method`).

### Remove from Blocklist — `DELETE /blocklist`

Remove an entry from the blocklist so the card BIN, extended card BIN, or fingerprint can transact again. The request body uses the same `type`/`data` shape as Add to Blocklist.

### Toggle Blocklist — `POST /blocklist/toggle`

Enable or disable blocklist enforcement for the merchant. Disabling the guard retains entries but stops them blocking payments. Pass the desired state as a `status` query parameter (`true` to enable, `false` to disable).

Request body:

```json
{
  "status": true
}
```

## Authentication

### Create Authentication — `POST /authentication`

Create an authentication session

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "return_url": "https://example.com/3ds-complete"
}
```

### Check Eligibility — `POST /authentication/{authentication_id}/eligibility`

Check authentication eligibility

Path parameters: `authentication_id`

Request body:

```json
{
  "payment_method": "card",
  "card_number": "4242424242424242"
}
```

### Authenticate — `POST /authentication/{authentication_id}/authenticate`

Perform authentication

Path parameters: `authentication_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### Redirect — `POST /authentication/{authentication_id}/redirect`

Handle authentication redirect

Path parameters: `authentication_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### Sync Authentication — `POST /authentication/{authentication_id}/sync`

Sync authentication status

Path parameters: `authentication_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

### POST Eligibility Check — `POST /authentication/{authentication_id}/eligibility-check`

Check eligibility via POST

Path parameters: `authentication_id`

Request body:

```json
{
  "card_number": "4242424242424242"
}
```

### GET Eligibility Check — `GET /authentication/{authentication_id}/eligibility-check`

Check eligibility via GET

Path parameters: `authentication_id`

### Enable Auth Methods Token — `POST /authentication/{authentication_id}/enabled_authn_methods_token`

Enable authentication methods token

Path parameters: `authentication_id`

Request body:

```json
{
  "client_secret": "{{client_secret}}"
}
```

## 3DS Decision

### Execute 3DS Decision — `POST /three_ds_decision/execute`

Execute a 3DS decision rule

Request body:

```json
{
  "routing_id": "{{routing_algorithm_id}}",
  "payment": {
    "amount": 6500,
    "currency": "ZAR"
  }
}
```

---

Interactive version: https://playground.peachpayments.com/playground