Sign in

Payments

Metadata reference

View as Markdown

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

FieldTypeConstraints / behavior
any custom keyJSON valueReturned in API responses. Regular key/value pairs do not display on the dashboard transaction view.
custom_fieldsarray of objectsReserved array for dashboard-visible fields.
cancel_actionstringFully qualified URL used as the destination when a customer cancels payment.
custom_filtersobjectReserved object for payment-channel and recurring filters.

Copy linkcustom_fields[]

Each item in custom_fields is an object with three keys.

FieldTypeConstraints / behavior
display_namestringLabel shown on the dashboard transaction view.
variable_namestringInternal key name for the field.
valuestringDisplayed value for the custom field.

Copy linkcustom_filters

FieldTypeConstraints / behavior
recurringbooleanEnables recurring-oriented filtering. Supported for card and Pay with Bank flows.
banksarray of stringsAccepts bank codes for restricting accepted bank cards.
card_brandsarray of stringsRestricts accepted card brands. Supported values: verve, visa, amex, mastercard.
supported_bank_providersarray of stringsRestricts Pay with Bank to specific bank codes.
supported_mobile_money_providersarray of stringsRestricts mobile money options to specific provider codes.

Copy linkCard brand codes

BrandCodeAvailability
VerveverveNigeria
VisavisaAll regions
American ExpressamexNigeria, Kenya, South Africa
MastercardmastercardAll regions

Copy linkMobile money provider codes

ProviderCodeCountry
MTNmtnGhana
AirtelTigoatlGhana
VodafonevodGhana

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?