Stored Payment Methods

Aperçu

Stored Payment Method est utilisé quand un client autorise un marchand à stocker les identifiants de paiement pour des paiements futurs. Par exemple, un payeur peut choisir de sauvegarder sa carte au checkout. Dans ce cas, un jeton unique est généré par la Payment Gateway qui lie le numéro de carte du payeur (PAN) à son ID dans le système du magasin (par exemple, au login du payeur).

Stockage d'une Payment Method

Vous pouvez stocker une Payment Method pendant le paiement. À cette fin, vous devez créer une Session (si l'intégration redirect est utilisée) en utilisant la méthode /sessions ou créer un Payment (si l'intégration redirect ou direct est utilisée) en utilisant la méthode /payments (voir la API Reference pour les détails). Dans chacune de ces méthodes, vous devez spécifier les paramètres suivants :

• merchantCustomerID - un identifiant de votre client, toutes les cartes du client seront attachées à ce numéro. À des fins de test, vous pouvez utiliser n'importe quelle combinaison de symboles (de 8 à 50) comme merchantCustomerID. Les symboles autorisés sont les chiffres, les caractères latins, _, et -.
• setupFutureUsage - le bloc avec des informations sur la catégorie Payment Method et l'usage futur. Ce bloc contient les paramètres suivants :

Exemple de section setupFutureUsage :

"setupFutureUsage": {
    "category": "recurrent",
    "recurringModel": {
        "recurrent": {
            "expiry": "2025-08-24",
            "frequency": 1
        }
    }
}

Après un paiement réussi, la Payment Method sera stockée. L'identifiant de la Stored Payment Method créée sera retourné dans les webhooks suivants :

• paymentMethod.created - dans le paramètre id
• payment.succeeded - dans le paramètre storedPaymentMethodId

Pour les détails, référez-vous à Webhooks.

Vous pouvez également récupérer l'identifiant de la Stored Payment Method créée en envoyant la requête /payments/{id} où id est l'identifiant du Payment. L'identifiant de la Store Payment Method sera retourné dans le paramètre storedPaymentMethodId de la réponse. Pour plus de détails, consultez API Reference.

Récupération des Stored Payment Methods

Pour récupérer une Payment Method particulière, utilisez la requête GET paymentMethods/{id}, où id est l'identifiant de la Payment Method. Payment Gateway retournera l'objet PaymentMethod avec l'identifiant spécifié. Pour plus de détails, consultez API Reference.

Exemple de requête :

curl -X GET "https://dev.bpcbt.com/api2/paymentmethods/pm_01491394-63a6-7d45-a88f-7bce00a7d8c0"\
  -H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
  -H "X-Version: 2023-10-31" \

Exemple de réponse :

{
  "id": "pm_01491394-63a6-7d45-a88f-7bce00a7d8c0",
  "active": true,
  "expiryDate": "2024-08-24",
  "category": "unscheduled",
  "created": "2023-08-24T14:15:22Z",
  "merchantCustomerId": "string",
  "type": "card",
  "card": {
    "expiryMonth": 12,
    "expiryYear": 2024,
    "holderName": "TEST CARDHOLDER",
    "maskedNumber": "411111**1111"
  }  
}

Vous pouvez également récupérer la liste de toutes les Stored Payment Methods d'un client particulier. À cette fin, utilisez la requête /customers/{id}/paymentMethods où id est un identifiant du client. Pour plus de détails, consultez API Reference.

Exemple de requête :

curl -X GET "https://dev.bpcbt.com/api2/customers/123/paymentMethods" \
  -H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
  -H "X-Version: 2023-10-31" \

Exemple de réponse :

{
  "hasMore": false,
  "list": [
{
  "id": "pm_01491394-63a6-7d45-a88f-7bce00a7d8c0",
  "active": true,
  "expiryDate": "2024-08-24",
  "category": "unscheduled",
  "created": "2023-08-24T14:15:22Z",
  "merchantCustomerId": "string",
  "type": "card",
  "card": {
    "expiryMonth": 12,
    "expiryYear": 2024,
    "holderName": "TEST CARDHOLDER",
    "maskedNumber": "411111**1111"
  }  
},
{
  "id": "pm_01591394-63a6-7d45-a88f-7bce00a7d8b0",
  "active": true,
  "expiryDate": "2024-08-24",
  "category": "unscheduled",
  "created": "2023-08-24T14:15:22Z",
  "merchantCustomerId": "string",
  "type": "applePay",
  "applePay": {
        "token": "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0="
  }  
]
}

Mise à jour des Stored Payment Methods

Vous pouvez activer ou désactiver une Payment Method ainsi que changer sa date d'expiration en utilisant la requête /paymentMethods/id, où id est l'identifiant de la Payment Method. La requête doit contenir les paramètres suivants :

• active — Indique une Payment Method active ou inactive (true ou false). Les paiements ne peuvent pas être effectués avec une PaymentMethod inactive.
• expiryDate — La date après laquelle les paiements ne sont pas autorisés avec cette Payment Method.

Pour plus de détails, consultez API Reference.

Exemple de requête :

curl -X POST "https://dev.bpcbt.com/api2/paymentMethods/pm_01491394-63a6-7d45-a88f-7bce00a7d8c0" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
-H "Content-Type: application/json" \
-d '{
  "active": true,
  "expiryDate": "2025-08-24"
}'

Exemple de réponse :

{
  "id": "pm_01491394-63a6-7d45-a88f-7bce00a7d8c0",
  "active": true,
  "expiryDate": "2025-08-24",
  "category": "unscheduled",
  "created": "2023-08-24T14:15:22Z",
  "merchantCustomerId": "string",
  "type": "card",
  "card": {
    "expiryMonth": 12,
    "expiryYear": 2024,
    "holderName": "TEST CARDHOLDER",
    "maskedNumber": "411111**1111"
  }  
}

Paiement avec une Stored Payment Method

Pour payer en utilisant une Stored Payment Method, il est nécessaire de passer son identifiant dans le paramètre storedPaymentMethodId de la requête de création de Payment (/payments). Pour plus de détails, consultez API Reference.

Exemple de requête :

curl -X POST "https://dev.bpcbt.com/api2/paymens" \
-H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \
-H "Content-Type: application/json" \
-d '{
  "amount": 10000,
  "currency": "EUR",
  "customerDetails": {
    "address": {
      "city": "Test city",
      "country": "Test country",
      "line1": "Test address1",
      "line2": "Test address2",
      "postalCode": "Test postal code",
      "state": "Test state"
    },
    "email": "test@example.com",
    "name": "TEST CARDHOLDER",
    "phone": "+449998887766"
  },
  "description": "Some description",
  "merchantCustomerID": "string",
  "metadata": {},
  "storedPaymentMethod": "pm_01491394-63a6-7d45-a88f-7bce00a7d8c0",  
  "setupFutureUsage": {
    "category": " "
    }
  }
}'