API Changelog - 2026-06-25: Summary
A new metadata field has been added to all payment operation request bodies
and their corresponding response objects, allowing merchants to attach up to 50
custom key-value pairs for cross-referencing and reconciliation. Keys must match
[a-zA-Z0-9_-] (max 50 chars) and values are strings (max 100 chars). The
merchantAdviceCode field in Mastercard payment method responses is now
formally marked as deprecated in the API schema.
The paymentMethod.token.status field is now returned in payment and
transaction responses when a tokenized Visa, Mastercard, Maestro, or Troy card
payment is retrieved. The field indicates whether the token is currently active
or suspended.
POST /v1/payments — Create Payment
The request body now accepts an optional metadata object containing custom
key-value pairs. The field is also returned in the response.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Request body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
POST /v1/payments/{paymentId}/cancels — Cancel Payment
The request body now accepts an optional metadata object for associating
reconciliation data with the cancel operation.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Request body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
POST /v1/payments/{paymentId}/captures — Capture Payment
The request body now accepts an optional metadata object for associating
reconciliation data with the capture operation.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Request body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
POST /v1/payments/{paymentId}/increments — Increment Payment
The request body now accepts an optional metadata object for associating
reconciliation data with the increment operation.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Request body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
POST /v1/payments/{paymentId}/refunds — Refund Payment
The request body now accepts an optional metadata object for associating
reconciliation data with the refund operation.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Request body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
POST /v1/credits — Create Credit
The request body now accepts an optional metadata object. The field is also
returned in the credit response.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Request body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
GET /v1/payments — Get All Payments
Payment and credit items in the response list now include a metadata field
reflecting any metadata set on the original request.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Response body (data[]) |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
For Visa, Mastercard, Maestro, and Troy payment methods, the
paymentMethod.token object (present when the payment was made using a stored
card token) now includes a required status field. Integrations that read token
details from payment list responses should expect this field to always be
present.
| Property | Details |
|---|---|
| Name | paymentMethod.token.status |
| Location | Response body (data[]) |
| Type | string |
| Required | Yes — when paymentMethod.token is present |
| Format | Enum: active, suspended |
| Example | "active" |
GET /v1/payments/{paymentId} — Get Payment by ID
The payment response now includes a metadata field reflecting any metadata set
on the original create payment request.
The paymentMethod.merchantAdviceCode field for Mastercard payments is now
formally marked as deprecated in the API schema. Use the
paymentMethod.scheme.merchantAdviceCode field instead.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Response body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
| Property | Details |
|---|---|
| Name | paymentMethod.merchantAdviceCode |
| Location | Response body (Mastercard) |
| Type | string |
| Required | No (optional) |
| Format | Mastercard merchant advice code — deprecated |
| Example | "01" |
For Visa, Mastercard, Maestro, and Troy payment methods, the
paymentMethod.token object (present when the payment was made using a stored
card token) now includes a required status field. Integrations that read token
details from payment responses should expect this field to always be present.
| Property | Details |
|---|---|
| Name | paymentMethod.token.status |
| Location | Response body |
| Type | string |
| Required | Yes — when paymentMethod.token is present |
| Format | Enum: active, suspended |
| Example | "active" |
GET /v1/transactions — Get All Transactions
Transaction items in the response list now include a metadata field reflecting
any metadata set on the associated operation request.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Response body (data[]) |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
For payment-type transactions using Visa, Mastercard, Maestro, or Troy, the
paymentMethod.token object (present when the transaction used a stored card
token) now includes a required status field.
| Property | Details |
|---|---|
| Name | paymentMethod.token.status |
| Location | Response body (data[]) |
| Type | string |
| Required | Yes — when paymentMethod.token is present |
| Format | Enum: active, suspended |
| Example | "active" |
GET /v1/transactions/{transactionId} — Get Transaction by ID
The transaction response now includes a metadata field. Dependent transactions
embedded in the response also carry the metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Response body |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
Webhook /payment — Payment Notification
All payment webhook payloads (succeeded, pending, declined, not-succeeded,
verified) now include a metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Webhook payload |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
Webhook /cancel — Cancel Notification
All cancel webhook payloads (succeeded, pending, declined, not-succeeded) now
include a metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Webhook payload |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
Webhook /capture — Capture Notification
All capture webhook payloads (succeeded, pending, not-succeeded) now include a
metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Webhook payload |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
Webhook /increment — Increment Notification
All increment webhook payloads (succeeded, pending, declined, not-succeeded) now
include a metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Webhook payload |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
Webhook /refund — Refund Notification
All refund webhook payloads (succeeded, pending, not-succeeded) now include a
metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Webhook payload |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
Webhook /credit — Credit Notification
All credit webhook payloads (succeeded, declined, not-succeeded) now include a
metadata field.
| Property | Details |
|---|---|
| Name | metadata |
| Location | Webhook payload |
| Type | object |
| Required | No (optional) |
| Format | Key-value pairs — added |
| Example | {"invoiceReference": "INV-12345"} |
For payment-type transactions using Visa, Mastercard, Maestro, or Troy, the
paymentMethod.token object (present when the transaction used a stored card
token) now includes a required status field.
| Property | Details |
|---|---|
| Name | paymentMethod.token.status |
| Location | Response body |
| Type | string |
| Required | Yes — when paymentMethod.token is present |
| Format | Enum: active, suspended |
| Example | "active" |