Points de terminaison de l'API de Snipcart

L'url de base pour l'API de la passerelle de paiement personnalisée est https://payment.snipcart.com/api

Valider le jeton public

GET /public/custom-payment-gateway/validate?publicToken=<SOME_TOKEN>

Ceci est important pour éviter les paiements frauduleux
Lorsque nous appelons votre API, nous envoyons toujours un publicToken. Utilisez ce point de terminaison pour valider que la demande a été faite par notre API.
Ce jeton doit toujours être validé pour éviter les tentatives frauduleuses.

Requête

publicTokenstring - Obligatoire
La clé publique d'une session de paiement en cours.

curl --request GET \
  --url 'https://payment.snipcart.com/api/public/custom-payment-gateway/validate?publicToken=<SOME_TOKEN>' \


Récupérer une session de paiement

GET /public/custom-payment-gateway/payment-session?publicToken=<SOME_TOKEN>
Récupère la session de paiement à partir du publicToken.

Requête

publicTokenstring - Obligatoire
La clé publique d'une session de paiement en cours.

curl --request GET \
  --url 'https://payment.snipcart.com/api/public/custom-payment-gateway/payment-session?publicToken=<SOME_TOKEN>' \

Réponse

idGuid
L'identifiant de la session de paiement.

invoiceInvoice
La facture de la session

paymentAuthorizationRedirectUrlstring
L'URL à laquelle rediriger une fois que le processus de paiement est terminé.

{
  "invoice": {
    "shippingAddress": {
      "name": "John Doe",
      "streetAndNumber": "123 Street",
      "postalCode": "12345",
      "country": "US",
      "city": "Cuppertino",
      "region": null
    },
    "billingAddress": {
      "name": "John Doe",
      "streetAndNumber": "123 Street",
      "postalCode": "12345",
      "country": "US",
      "city": "Cuppertino",
      "region": null
    },
    "email": "john.doe@example.com",
    "language": "en",
    "currency": "usd",
    "amount": 409.29,
    "targetId": "226086da-57be-4b92-b950-5fd632be7767",
    "items": [
      {
        "name": "Rosy-Fingered Dawn at Louse Point",
        "unitPrice": 49.95,
        "quantity": 1,
        "type": "Physical",
        "rateOfTaxIncludedInPrice": 0,
        "amount": 49.95
      },
      {
        "name": "Starry Night",
        "unitPrice": 79.95,
        "quantity": 3,
        "type": "Physical",
        "rateOfTaxIncludedInPrice": 0,
        "amount": 239.85
      },
      {
        "name": "Sales tax",
        "unitPrice": 19.49,
        "quantity": 1,
        "type": "Tax",
        "rateOfTaxIncludedInPrice": 0,
        "amount": 19.49
      },
      {
        "name": "FREE SHIPPING OVER 250$",
        "unitPrice": 0,
        "quantity": 1,
        "type": "Shipping",
        "rateOfTaxIncludedInPrice": 0,
        "amount": 0
      }
    ]
  },
  "id":"b2eb036a-842ee242-0d2d-4fad-bc9a-de16411fc6d1",
  "paymentAuthorizationRedirectUrl":"https://example.com#/checkout",
}


Créer le paiement

POST /private/custom-payment-gateway/payment
Crée un paiement pour la session de paiement (confirme le paiement)

Requête

En-têtes
Authorizationstring - Obligatoire
Bearer <YOUR_SECRET_API_KEY> L'en-tête de requête d'autorisation est utilisé pour valider vos informations d'identification auprès du serveur. Sa valeur doit être un jeton porteur qui contient votre clé API secrète.

Content-Typestring - Obligatoire
application/json Notre API n'accepte que le type de contenu application/json, vous devez donc toujours spécifier le type de contenu application/json dans chaque requête que vous effectuez.

Corps
paymentSessionIdstring - Obligatoire
L'identifiant de la session de paiement

state"processing" | "processed" | "invalidated" | "failed" - Obligatoire
L'état actuel du paiement. Les valeurs possibles sont : processing, processed, invalidated et failed.

transactionIdstring - Obligatoire
L'identifiant unique de la transaction. Il est souvent fourni par la passerelle de paiement.

errorError Représente le message d'erreur que vous souhaitez afficher au client dans l'étape de paiement, le cas échéant.

Erreur
codestring - Obligatoire
Ceci est utilisé pour localiser le message dans le panier.
messagestring
Ceci est utilisé comme valeur de remplacement lorsque aucune correspondance n'est trouvée pour code.

instructionsstring
Instructions supplémentaires que vous souhaitez afficher à votre client dans l'écran de confirmation de la commande.

L'objet `links` contient les liens utilitaires pour le paiement. Par exemple, vous pouvez spécifier l'URL de remboursement en utilisant la clé `refunds`.

Links
refundsstring Ceci sera appelé lorsqu'un remboursement sera effectué via le tableau de bord du commerçant.

curl --request POST \
  --url https://payment.snipcart.com/api/private/custom-payment-gateway/payment \
  --header 'Authorization: Bearer <YOUR_SECRET_API_KEY>' \
  --header 'content-type: application/json' \
  --data '{
        "paymentSessionId": "5e921d3b-8756-4fd0-87e9-c72f946535ed",
        "state": "failed",
        "error": {
            "code": "card_declined",
            "message": "Your card was declined"
        }
}'

Vos webhooks

Ce sont les points de terminaison de l'API que vous devrez créer pour intégrer votre propre passerelle de paiement. Notre API les appellera avec un publicToken dans le corps de la requête. N'oubliez pas de valider la requête en utilisant le point de terminaison /validate

Méthodes de paiement

Le premier point de terminaison important que votre API doit avoir est celui qui retourne les méthodes de paiement disponibles. Lorsqu'un client procède au paiement, nous appelons le point de terminaison de votre API pour lui montrer les méthodes de paiement disponibles.

Nous allons envoyer une requête POST à l'URL de la méthode de paiement spécifiée dans le tableau de bord du commerçant.

Nous nous attendons à recevoir un array de PaymentMethod.

Requête

Méthode POST

Corps
invoiceInvoice
La facture de la commande en cours

publicTokenstring
Utilisé pour valider que la demande a été faite par Snipcart.

mode"test" | "live"
Le mode de commande.

{
  "invoice": {
    "shippingAddress": {
      "name": "John Doe",
      "streetAndNumber": "123 Street",
      "postalCode": "12345",
      "country": "US",
      "city": "Cuppertino",
      "region": null
    },
    "billingAddress": {
      "name": "John Doe",
      "streetAndNumber": "123 Street",
      "postalCode": "12345",
      "country": "US",
      "city": "Cuppertino",
      "region": null
    },
    "email": "john.doe@example.com",
    "language": "en",
    "currency": "usd",
    "amount": 409.29,
    "targetId": "226086da-57be-4b92-b950-5fd632be7767",
    "items": [
      {
        "name": "Rosy-Fingered Dawn at Louse Point",
        "unitPrice": 49.95,
        "quantity": 1,
        "type": "Physical",
        "rateOfTaxIncludedInPrice": 0,
        "amount": 49.95
      },
      ...
    ]
  },
  "publicToken": "<JWT_TOKEN>",
  "mode": "test"
}

Réponse

Corps
PaymentMethods[] - Obligatoire
Les méthodes de paiement disponibles pour la commande en cours.

PaymentMethod
idstring - Obligatoire
Il s'agit de l'identifiant de la méthode de paiement.

namestring - Obligatoire
Le nom de la méthode de paiement (il sera affiché pendant la phase de paiement).

checkoutUrlstring - Obligatoire
L'URL de votre page de paiement.

iconUrlstring
Si vous souhaitez afficher une icône au lieu d'un nom pendant la phase de paiement, vous pouvez la définir ici.

Notez que seul le nom ou l'icône sera affiché, pas les deux.

{
  "headers": {
    "content-type": "application/json"
  },
  "body": [
    {
      "id": "snipcart_custom_gatway_1",
      "name": "Custom gateway 1",
      "checkoutUrl": "https://snipcart.com/checkout_gateway_1",
    },
    {
      "id": "snipcart_custom_gatway_2",
      "name": "Custom gateway 2",
      "checkoutUrl": "https://snipcart.com/checkout_gateway_2",
      "iconUrl": "https://snipcart.com/checkout_gateway_2/icon.png"
    }
  ]
}

Remboursement

Il s'agit du point de terminaison de remboursement que vous pouvez fournir lors de la confirmation du paiement avec notre API. Lors du remboursement d'un client à partir du tableau de bord du commerçant, ce point de terminaison sera appelé.

Requête

Méthode POST

Corps
paymentIdstring
Le paiement que nous voulons rembourser.

amountnumber
Le montant à rembourser.

{
  "paymentId": "d3031d89-e428-4cb8-bf0e-74b883466736",
  "amount": 20.75
}

Réponse

refundIdGuid
L'identifiant du remboursement.

{
  "body": {
      "refundId": "940bb5bc-13f7-4d02-987f-fad12ab98ebb"
  }
}

Types

Facture

shippingAddressAddress
L'adresse de livraison de la commande.

billingAddressAddress
L'adresse de facturation de la commande.

emailstring
L'adresse courriel du client.

languagestring
La langue du panier.

currencystring
La devise de la commande.

amountnumber
Le total de la commande.

targetIdGuid
L'identifiant du panier

itemsItem[]
Les articles de la commande.

{
  "shippingAddress": {
    ...
  },
  "billingAddress": {
    ...
  },
  "email": "john.doe@example.com",
  "language": "en",
  "currency": "usd",
  "amount": 409.29,
  "targetId": "226086da-57be-4b92-b950-5fd632be7767",
  "items": [
    ...
  ]
}


Addresse

namestring
Nom complet du destinataire (prénom et nom de famille)

streetAndNumberstring
Rue et numéro de rue civique.

postalCodestring

countrystring

citystring

{
  "name": "John Doe",
  "streetAndNumber": "123 Street",
  "postalCode": "12345",
  "country": "US",
  "city": "Cuppertino",
  "region": null
}


Article

namestring

unitPricenumber
Le prix de l'article

quantitynumber

type"Physical" | "Digital" | "Tax" | "Shipping" | "Discount"
Représente le type d'article.

rateOfTaxIncludedInPricenumber

amountnumber
La quantité * prix unitaire

{
  "name": "Rosy-Fingered Dawn at Louse Point",
  "unitPrice": 49.95,
  "quantity": 1,
  "type": "Physical",
  "rateOfTaxIncludedInPrice": 0,
  "amount": 49.95
}