Metadata - Mercy Pay

metadata garde vos propres repères sur un objet : un numéro de commande, l’id d’un client dans votre système. Mercy Pay les renvoie tels quels dans les réponses et dans les webhooks.

curl https://mercy-pay.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "metadata": { "order_id": "CMD-2041", "store": "Douala Akwa" }
  }'

Où les utiliser

metadata est accepté sur les sessions de checkout, les paiements, les retraits, les liens de paiement, les plans, les abonnements et les clients. Deux objets reprennent ceux d’un autre :

un paiement reprend la metadata de sa session de checkout. Le webhook payment.succeeded vous dit donc directement quelle commande est payée ;
une facture reprend celle de son abonnement.

Limites

50 clés au plus ;
une clé fait 40 caractères au plus ;
une valeur est un texte, un nombre ou un booléen de 500 caractères au plus. Un objet ou une liste est refusé.

Ne mettez jamais de donnée sensible dans metadata : ni mot de passe, ni numéro de carte.

Modifier

Sur un client, PATCH fusionne clé par clé : une clé envoyée à null est retirée, les autres restent. "metadata": null retire toutes les clés.

curl -X PATCH https://mercy-pay.com/api/v1/customers/cus_c71d0e5a3b2f4e8a9c1d5f6a7b8c9d01 \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "segment": null, "city": "Douala" } }'