# Metadata reference

> 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.

## Top-level metadata keys

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Constraints / behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      any custom key
    </td>
    
    <td>
      JSON value
    </td>
    
    <td>
      Returned in API responses. Regular key/value pairs do not display on the dashboard transaction view.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        custom_fields
      </code>
    </td>
    
    <td>
      array of objects
    </td>
    
    <td>
      Reserved array for dashboard-visible fields.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cancel_action
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Fully qualified URL used as the destination when a customer cancels payment.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        custom_filters
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Reserved object for payment-channel and recurring filters.
    </td>
  </tr>
</tbody>
</table>

## `custom_fields[]`

Each item in `custom_fields` is an object with three keys.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Constraints / behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        display_name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Label shown on the dashboard transaction view.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        variable_name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Internal key name for the field.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        value
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Displayed value for the custom field.
    </td>
  </tr>
</tbody>
</table>

## `custom_filters`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Constraints / behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        recurring
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      Enables recurring-oriented filtering. Supported for card and Pay with Bank flows.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        banks
      </code>
    </td>
    
    <td>
      array of strings
    </td>
    
    <td>
      Accepts bank codes for restricting accepted bank cards.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        card_brands
      </code>
    </td>
    
    <td>
      array of strings
    </td>
    
    <td>
      Restricts accepted card brands. Supported values: <code>
        verve
      </code>
      
      , <code>
        visa
      </code>
      
      , <code>
        amex
      </code>
      
      , <code>
        mastercard
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        supported_bank_providers
      </code>
    </td>
    
    <td>
      array of strings
    </td>
    
    <td>
      Restricts Pay with Bank to specific bank codes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        supported_mobile_money_providers
      </code>
    </td>
    
    <td>
      array of strings
    </td>
    
    <td>
      Restricts mobile money options to specific provider codes.
    </td>
  </tr>
</tbody>
</table>

## Card brand codes

<table>
<thead>
  <tr>
    <th>
      Brand
    </th>
    
    <th>
      Code
    </th>
    
    <th>
      Availability
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Verve
    </td>
    
    <td>
      <code>
        verve
      </code>
    </td>
    
    <td>
      Nigeria
    </td>
  </tr>
  
  <tr>
    <td>
      Visa
    </td>
    
    <td>
      <code>
        visa
      </code>
    </td>
    
    <td>
      All regions
    </td>
  </tr>
  
  <tr>
    <td>
      American Express
    </td>
    
    <td>
      <code>
        amex
      </code>
    </td>
    
    <td>
      Nigeria, Kenya, South Africa
    </td>
  </tr>
  
  <tr>
    <td>
      Mastercard
    </td>
    
    <td>
      <code>
        mastercard
      </code>
    </td>
    
    <td>
      All regions
    </td>
  </tr>
</tbody>
</table>

## Mobile money provider codes

<table>
<thead>
  <tr>
    <th>
      Provider
    </th>
    
    <th>
      Code
    </th>
    
    <th>
      Country
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      MTN
    </td>
    
    <td>
      <code>
        mtn
      </code>
    </td>
    
    <td>
      Ghana
    </td>
  </tr>
  
  <tr>
    <td>
      AirtelTigo
    </td>
    
    <td>
      <code>
        atl
      </code>
    </td>
    
    <td>
      Ghana
    </td>
  </tr>
  
  <tr>
    <td>
      Vodafone
    </td>
    
    <td>
      <code>
        vod
      </code>
    </td>
    
    <td>
      Ghana
    </td>
  </tr>
</tbody>
</table>

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.
