# Create a payment

`POST https://app.shuttleglobal.com/c/api/instances/{instance_key}/payments`

Create a new payment. The payment can be immediate or scheduled, one-time or recurring.
Unless rejected prior to processing, the API request will succeed and return a payment object
in a SUCCESS or DECLINE status.

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Request body (`application/json`), required

- `payment` (object, required): Payment details object
  - `currency` (string, required): The currency in ISO format (e.g., USD)
  - `amount` (string): The payment amount as a string without commas, using '.' as decimal separator. Required in the standard case. Optional when `charges` is provided — if omitted, it is derived from the sum of `charges[].amount`; if supplied, it must equal that sum.
  - `alt_key` (string): Your unique reference for the payment (e.g., order id). URL friendly string, max 64 chars (a-z0-9_-)
  - `description` (string): Descriptive text for the payment
  - `nonce` (string): Unique string to prevent duplicate submissions within 24 hours
  - `action` (string): Payment action type One of: `PAYMENT`, `AUTH`.
  - `source` (string): Source of the payment One of: `MOTO`, `ECOMMERCE`, `RECURRING`.
  - `success_url` (string (uri)): URL to redirect on successful 3D secure completion
  - `cancel_url` (string (uri)): URL to redirect on 3D secure cancellation
  - `payment_method` (one of)
  - `account` (one of)
  - `frequency` (string): Payment frequency for recurring payments. Cannot be used together with `charges`; to use scheduled charges, omit `frequency` or set it to `ONEOFF`. One of: `ONEOFF`, `WEEKLY`, `FORTNIGHTLY`, `BIMONTHLY`, `MONTHLY`, `QUARTERLY`, `BIANNUALLY`, `ANNUALLY`.
  - `occurrences` (integer): Number of payments for recurring payments (blank = forever)
  - `start_date` (string (date-time)): When to take first payment for recurring payments (up to 365 days future)
  - `start_days` (integer): Days from now for first recurring payment (up to 31 days)
  - `scheduled_date` (string (date-time)): When to process one-time payment (up to 365 days future)
  - `scheduled_days` (integer): Days from now for one-time payment (up to 31 days)
  - `charges` (array of object): Explicit schedule of charges for the contract. Use this when charge amounts or due dates vary between charges (e.g., instalment plans with irregular amounts or dates). All charges are created upfront at contract creation. **When each charge is taken:** * `due: "now"` or a past timestamp (within the last 24 hours) — taken **synchronously** as part of contract creation. If the charge declines, contract creation fails and no contract is created. * `due` set to a future timestamp — taken **asynchronously** by the scheduler on the due date. The contract is created regardless of the outcome of that later payment. To have the first charge run asynchronously, set its `due` to a future timestamp (even a few minutes ahead). **Constraints:** * Cannot be combined with `frequency` (must be omitted or `ONEOFF`). * Not supported with `action: AUTH`. * Each charge's `due` cannot be more than 24 hours in the past. * The top-level `amount` is optional when `charges` is provided. If you do provide `amount`, it must equal the sum of `charges[].amount`.
    - `alt_key` (string): Optional — your unique reference for this charge (e.g., instalment number or invoice line id). URL friendly string, max 64 chars (a-z0-9_-)
    - `amount` (string, required): The charge amount as a string without commas, using '.' as decimal separator. Must be greater than zero.
    - `due` (string, required): When this charge is due. Accepts either the literal string `"now"`, or an ISO 8601 timestamp. * `"now"` or a past timestamp (within the last 24 hours) — taken **synchronously** during contract creation. A decline blocks the whole contract creation. * Future timestamp — taken **asynchronously** by the scheduler on the due date. The contract is created regardless of that later payment's outcome. A timestamp more than 24 hours in the past is rejected.
  - `gateway` (string): Gateway ID to process the payment through. If not specified, the default gateway will be used
  - `save_card` (boolean): Whether to save the card for future use
  - `force_payment_method` (boolean): Force creation of a new payment method even if a matching one already exists
  - `contract` (string): Contract ID for one-time payment on existing contract
  - `legal_entity` (string): Legal entity ID or code processing the payment
  - `event_date` (string (date-time)): Event date associated with the payment
  - `metadata` (object): Custom key-value pairs that will be stored on the contract
  - `shipping` (object): Shipping address for the order
    - `country` (string): Country code
    - `line1` (string): Address line 1
    - `line2` (string): Address line 2
    - `line3` (string): Address line 3
    - `line4` (string): City / Town
    - `line5` (string): Postcode / ZIP
    - `line6` (string): State / Region
  - `line_items` (array of object): The order basket. Optional, but required by BNPL providers and by some acquirers to qualify for Level 2 / Level 3 interchange rates on commercial cards. Include every line that makes up the payment `amount`, including shipping and tax lines.
    - `name` (string): Display name of the item. Shown to the customer in wallet sheets and BNPL baskets, and used as the item description for Level 2/3 data. Some gateways truncate this aggressively (Authorize.Net to 31 characters, Fat Zebra to 40), so keep it short.
    - `sku` (string): Your product code / SKU for the item. **PayPal only:** a line item whose `sku` is `shipping`, `handling` or `insurance` (case-insensitive) is removed from the basket and its `total_amount` is reported in the corresponding PayPal order breakdown field instead of as a basket line.
    - `description` (string): Longer description of the item, where `name` is not enough. Only used by gateways that accept a separate description field; those gateways fall back to `name` when this is omitted.
    - `quantity` (number): Number of units of this item.
    - `unit_of_measure` (string): Unit that `quantity` is expressed in — for example `each`, `hours`, `metres`. Used in Level 3 interchange data, where the card networks require it. Alphanumeric, maximum 12 characters; a longer or malformed value is replaced with `each`, as is an absent one.
    - `unit_price` (number): Gross price of a single unit, in major currency units, including tax.
    - `total_amount` (number): Gross total for the line, in major currency units, including tax and after any discount. See the discount formula above.
    - `total_tax` (number): Tax included in `total_amount` for this line, in major currency units. Send `0` for a tax-free line rather than omitting the field — several gateways sum this across the basket to report an order-level tax total.
    - `total_discount` (number): Explicit discount applied to this line, in major currency units. Only used by gateways that accept a discount amount per line (CyberSource, Worldpay). Other gateways derive the discount from `(quantity x unit_price) - total_amount`. Express the discount this way rather than as a negative line item. A negative line is not forwarded as Level 2/3 data.
    - `tax_rate` (number): Tax rate applied to this line, passed through unchanged. Only used by gateways that accept an explicit rate (currently CyberSource, which expects a decimal fraction — `0.2` for 20%). Where it is omitted, gateways that need a rate derive one from `total_tax` and `total_amount`.
    - `discount_rate` (number): Discount rate applied to this line, passed through unchanged. Only used by gateways that accept an explicit rate (currently CyberSource).
    - `item_url` (string (uri)): HTTPS URL of the product page for this item. Displayed by BNPL providers (Klarna, Affirm) in the basket they present to the customer.
    - `image_url` (string (uri)): HTTPS URL of a product image for this item. Displayed by BNPL providers (Klarna, Affirm) in the basket they present to the customer.
  - `hotel_data` (object): Hotel-specific data passed through to the payment gateway

## Responses

### 200: Payment created

```json
{
  "payment": {
    "id": "pay_11842_10000",
    "alt_key": "1234",
    "description": "Invoice 1234",
    "source": "MOTO",
    "action": "PAYMENT",
    "status": "SUCCESS",
    "gateway_status": "APPROVED",
    "gateway_reference": "ch_1GVaEEFi2CnH4uN3ouw69fw3",
    "authorisation_code": "pi_1GVaEEFi2CnH4uN355ZdZvk5 (TEST)",
    "reference": "REF-00010000",
    "amount": "100",
    "balance": "100",
    "currency": "GBP",
    "resolved": "2026-01-01T12:00:00Z",
    "sub_status": "CUSTOMER_ACTION_REQUIRED",
    "sub_status_reason": "follow_bank_transfer_instructions",
    "target_date": "2020-04-13T00:00:00.000Z",
    "settle_currency": "GBP",
    "settle_gross_amount": "100",
    "settle_net_amount": "96.9",
    "settle_fee_amount": "3.1",
    "gateway": "gw_11842_10000",
    "account": "acc_11842_10000",
    "payment_method": "pm_11842_10000",
    "contract": "co_11842_10000",
    "channel": "ch_11842_10001",
    "initiative": "in_11842_10000",
    "designation": "des_11842_10000",
    "legal_entity": "le_11842_10000",
    "created": "2020-04-08T09:29:48.000Z",
    "updated": "2020-04-08T09:29:52.000Z",
    "processed": "2020-04-08T09:29:51.000Z",
    "gateway_metadata": {},
    "payment_method_used_token": false,
    "recurring": false,
    "frequency": "MONTHLY",
    "occurrences": 12,
    "browser_ip_address": "212.161.80.4"
  },
  "contract": {
    "id": "co_11842_10000",
    "account": "acc_11842_10000",
    "alt_key": "1234",
    "amount": "100",
    "currency": "GBP",
    "description": "Invoice 1234",
    "status": "COMPLETED",
    "recurring": false,
    "payment_method": "pm_11842_10000",
    "created": "2020-04-08T09:29:48.000Z",
    "updated": "2020-04-08T09:29:52.000Z",
    "initiated": "2020-04-08T09:29:48.000Z",
    "completed": "2020-04-08T09:29:52.000Z",
    "last_transaction": "tr_11842_10000",
    "frequency": "ONEOFF",
    "occurrences": 0,
    "next_charge": "2026-01-01T12:00:00Z",
    "charge_count": 0
  },
  "transaction": {
    "id": "tr_11842_10000",
    "action": "PAYMENT",
    "source": "MOTO",
    "status": "SUCCESS",
    "gateway_status": "APPROVED",
    "sub_status": "CUSTOMER_ACTION_REQUIRED",
    "sub_status_reason": "follow_bank_transfer_instructions",
    "gateway_reference": "ch_1GVaEEFi2CnH4uN3ouw69fw3",
    "authorisation_code": "pi_1GVaEEFi2CnH4uN355ZdZvk5 (TEST)",
    "reference": "REF-00010000",
    "amount": "100",
    "currency": "GBP",
    "created": "2020-04-08T09:29:48.000Z",
    "updated": "2020-04-08T09:29:52.000Z",
    "processed": "2020-04-08T09:29:51.000Z",
    "resolved": "2020-04-08T09:29:51.000Z",
    "target_date": "2020-04-13T00:00:00.000Z"
  },
  "id": "string",
  "alt_key": "string",
  "description": "string",
  "source": "MOTO",
  "action": "PAYMENT",
  "status": "SUCCESS"
}
```

### 400: Bad request - invalid parameters

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorized - invalid credentials

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

## Example request

```sh
curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payments \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment": {
    "currency": "GBP",
    "amount": "100.00",
    "alt_key": "order_123",
    "description": "Invoice 1234",
    "action": "PAYMENT",
    "source": "ECOMMERCE",
    "success_url": "https://www.myhost.com/success",
    "cancel_url": "https://www.myhost.com/cancel",
    "frequency": "MONTHLY",
    "occurrences": 12,
    "charges": [
      {
        "alt_key": "INSTALMENT_1",
        "amount": "100.00",
        "due": "now"
      },
      {
        "alt_key": "INSTALMENT_2",
        "amount": "50.00",
        "due": "2026-06-01T09:00:00Z"
      },
      {
        "alt_key": "INSTALMENT_3",
        "amount": "50.00",
        "due": "2026-07-01T09:00:00Z"
      }
    ],
    "metadata": {
      "order_id": "12345",
      "customer_reference": "CUS-001"
    },
    "line_items": [
      {
        "sku": "SHOE-10-BLK",
        "name": "Running shoes",
        "quantity": 2,
        "unit_price": 20,
        "total_amount": 40,
        "total_tax": 4
      },
      {
        "sku": "SHIPPING",
        "name": "Standard delivery",
        "quantity": 1,
        "unit_price": 4.99,
        "total_amount": 4.99,
        "total_tax": 0
      }
    ]
  }
}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/createpayment/