Metadata

Metadata allows you to add custom data to your request payload. This is useful for storing additional information like cart IDs, invoice numbers, or specific configuration flags that Paystack's standard parameters don't cover.

Crafting Metadata

There are two main ways to add parameters to the metadata object:

1. Key/Value Pairs

You can pass arbitrary key-value pairs. These are returned in the API response and webhooks but do not show up on the Paystack Dashboard interface.

$payload = [
    'email' => '[email protected]',
    'amount' => 5000,
    'metadata' => [
        'cart_id' => 398,
        'invoice_id' => 'INV-2025-001',
        'payment_medium' => 'mobile_app'
    ]
];

2. Custom Fields

The custom_fields key is reserved for an array of fields that will be displayed on the Paystack Dashboard when viewing a transaction.

Each custom field requires three keys:

• display_name: The label shown on the dashboard.
• variable_name: The internal key.
• value: The value to display.

$payload = [
    'email' => '[email protected]',
    'amount' => 5000,
    'metadata' => [
        'custom_fields' => [
            [
                'display_name' => 'Invoice ID',
                'variable_name' => 'invoice_id',
                'value' => '209'
            ],
            [
                'display_name' => 'Cart Items',
                'variable_name' => 'cart_items',
                'value' => '3 bananas, 12 mangoes'
            ]
        ]
    ]
];

Special Metadata Keys

Paystack recognizes specific keys within the metadata object to trigger special behaviors.

Cancel Action

Redirect users to a specific URL if they cancel the payment on the checkout page.

'metadata' => [
    'cancel_action' => 'https://your-site.com/checkout/cancelled'
]

Custom Filters

The custom_filters object within metadata allows you to control how a transaction is completed, such as restricting card brands or banks.

Recurring Payment

Force the transaction to use a method that supports recurring billing.

• Cards: Accepts only Verve cards with recurring support; forces bank authentication for Visa/Mastercard.
• Pay with Bank: Filters out banks that don't support recurring payments.

'metadata' => [
    'custom_filters' => [
        'recurring' => true
    ]
]

Selected Banks

Restrict the transaction to specific banks. Use the Miscellaneous Resource to get bank codes.

'metadata' => [
    'custom_filters' => [
        'banks' => ['057', '100'] // Zenith, Suntrust
    ]
]

Selected Card Brands

Restrict the transaction to specific card brands. Supported brands: verve, visa, mastercard.

'metadata' => [
    'custom_filters' => [
        'card_brands' => ['visa']
    ]
]

Selected Bank Accounts (Pay with Bank)

Specify which banks should be shown on the "Pay with Bank" channel.

'metadata' => [
    'custom_filters' => [
        'supported_bank_providers' => ['033', '215', '102']
    ]
]

Selected Mobile Money Providers

Restrict the Mobile Money providers available to the customer (e.g., in Ghana). Supported codes: mtn (MTN), atl (AirtelTigo), vod (Vodafone).

'metadata' => [
    'custom_filters' => [
        'supported_mobile_money_providers' => ['vod']
    ]
]

comprehensive Example

Combining multiple filters and custom fields:

$payload = [
    'email' => '[email protected]',
    'amount' => 10000,
    'metadata' => [
        'cart_id' => 'CART_123',
        'cancel_action' => 'https://myshop.com/cart',
        'custom_fields' => [
            [
                'display_name' => 'Customer Tier',
                'variable_name' => 'tier',
                'value' => 'Gold'
            ]
        ],
        'custom_filters' => [
            'recurring' => true,
            'card_brands' => ['visa', 'mastercard']
        ]
    ]
];

paystack()->transaction()->initialize($payload);