Payments
Metadata reference
In a nutshell
Reference for Paystack metadata fields, reserved keys, and custom filter options.
The metadata field accepts a JSON object of additional values attached to a transaction or related request. Arbitrary key/value pairs are returned in API responses. Reserved keys have special behavior.
Copy linkTop-level metadata keys
| Field | Type | Constraints / behavior |
|---|---|---|
| any custom key | JSON value | Returned in API responses. Regular key/value pairs do not display on the dashboard transaction view. |
custom_fields | array of objects | Reserved array for dashboard-visible fields. |
cancel_action | string | Fully qualified URL used as the destination when a customer cancels payment. |
custom_filters | object | Reserved object for payment-channel and recurring filters. |
Copy linkcustom_fields[]
Each item in custom_fields is an object with three keys.
| Field | Type | Constraints / behavior |
|---|---|---|
display_name | string | Label shown on the dashboard transaction view. |
variable_name | string | Internal key name for the field. |
value | string | Displayed value for the custom field. |
Copy linkcustom_filters
| Field | Type | Constraints / behavior |
|---|---|---|
recurring | boolean | Enables recurring-oriented filtering. Supported for card and Pay with Bank flows. |
banks | array of strings | Accepts bank codes for restricting accepted bank cards. |
card_brands | array of strings | Restricts accepted card brands. Supported values: verve, visa, amex, mastercard. |
supported_bank_providers | array of strings | Restricts Pay with Bank to specific bank codes. |
supported_mobile_money_providers | array of strings | Restricts mobile money options to specific provider codes. |
Copy linkCard brand codes
| Brand | Code | Availability |
|---|---|---|
| Verve | verve | Nigeria |
| Visa | visa | All regions |
| American Express | amex | Nigeria, Kenya, South Africa |
| Mastercard | mastercard | All regions |
Copy linkMobile money provider codes
| Provider | Code | Country |
|---|---|---|
| MTN | mtn | Ghana |
| AirtelTigo | atl | Ghana |
| Vodafone | vod | Ghana |
Metadata commonly carries values such as invoice IDs, cart IDs, cart items, or payment medium markers. Reserved keys change payment behavior; non-reserved keys simply travel with the transaction payload.
Was this page helpful?