Operation

Create payment

POST/payments

Create a new payment for an order

Headers

X-Ticketlayer-ChannelstringOptional: Slug of the sales channel to act through. A channel-scoped credential supplies its own channel and this header, when sent, must agree with it. On a read it filters to what that channel sells, at its resolved prices; on a cart it is required; on an order operation it is derived from the order and may only confirm it, never contradict it.
Idempotency-KeystringOptional: Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.

Body

accountId*stringAccount ID for tenant isolation

orderId*stringOrder ID this payment is for

orderNumber*stringHuman-readable order number

amount*numberPayment amount

currency*stringCurrency code (ISO 4217)

paymentProviderIdstringPayment provider ID (optional - will find by type if not provided)

returnUrlstring (uri)URL to redirect after payment

isPartialPaymentbooleanWhether this is a partial payment

remainingBalancenumberRemaining balance after this payment

metadataobjectCustom metadata

Returns

Payment created successfully

Errors

400: Bad Request - Invalid input
401: Unauthorized - Authentication required
403: Forbidden - Insufficient permissions
404: Not Found - Resource not found
500: Internal Server Error

Every error names its code and links to it. All error codes

curl -X POST "https://api.ticketlayer.com/v1/payments" \  -H "Authorization: Bearer tlak_..." \  -H "X-Ticketlayer-Org: your-org-slug" \  -H "Content-Type: application/json" \  -d '{    "accountId": "acc_xyz789",    "orderId": "ord_abc123",    "orderNumber": "ORD-ABC123",    "amount": 97,    "currency": "GBP",    "paymentType": "online_card",    "paymentProviderId": "ppr_stripeXxx123",    "returnUrl": "https://venue.com/orders/ord_xxx/confirmation",    "isPartialPayment": false,    "remainingBalance": 0,    "metadata": {      "customerEmail": "customer@example.com"    }  }'

Response 201

{
  "payment": {
    "id": "pay_abc123",
    "organisationId": "org_abc123",
    "invoiceId": "inv_abc123",
    "amount": 2500,
    "currency": "USD",
    "status": "succeeded",
    "method": "card",
    "paidAt": "2024-01-15T10:35:00Z",
    "failedAt": null,
    "failureCode": null,
    "failureMessage": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z"
  }
}

Create payment

Headers

Body

Returns

Errors

Try it in test mode

Body