Custom payment gateway: technical reference

Payment methods webhook

Whenever a customer reaches the payment step, a webhook is sent to your payment methods URL. This is where you can return a list of supported payment methods.

Request

Method POST

Parameters

Name Required? Type Description
publicToken Yes string The public key of an ongoing payment session.

Content-Type application/json

Body

{
  "mode": "Live",
  "invoice": {
    "shippingAddress": {
      "name": "Walter",
      "surname": "C Chapdelaine",
      "streetAndNumber": "4132  Woodstock Drive",
      "postalCode": "91731",
      "country": "US",
      "city": "El Monte",
      "region": null
    },
    "billingAddress": {
      "name": "Walter",
      "surname": "C Chapdelaine",
      "streetAndNumber": "4132  Woodstock Drive",
      "postalCode": "91731",
      "country": "US",
      "city": "El Monte",
      "region": null
    },
    "email": "i1p078uft4@powerencry.com",
    "language": "en",
    "currency": "cad",
    "amount": 169.9,
    "targetId": "789f6ba9-e033-4b37-a7e5-5829ea596510",
    "items": [
      {
        "name": "Starry Night",
        "unitPrice": 79.95,
        "quantity": 2,
        "type": "Physical",
        "discountAmount": 0,
        "rateOfTaxIncludedInPrice": 0,
        "amount": 159.9
      },
      {
        "name": "Livraison",
        "unitPrice": 10,
        "quantity": 1,
        "type": "Shipping",
        "discountAmount": 0,
        "rateOfTaxIncludedInPrice": 0,
        "amount": 10
      }
    ]
  }
}

Response

Snipcart expects to receive a JSON object containing an array of payment methods.

Headers

Name Value Required? Description
Content-Type application/json Yes Our API only accepts application/json content type, so you must always specify the application/json content type in each request you make.

Body

[
    {
        "id": "payment_method_id",
        "name": "Payment Method",
        "checkoutUrl": "https://yourdomain.com",
        "iconUrl": "https://yourdomain.com/assets/icon.svg"
    },
    {
        "id": "payment_method_id",
        "name": "Payment Method",
        "checkoutUrl": "https://yourdomain.com",
    },
    ...
]

GET /validate

Validates through the publicToken that the requests come from Snipcart. If the status code of the response is successful, you can assume that the request's origin is Snipcart.

Ressource URL

GET https://payment.snipcart.com/api/public/custom-payment-gateway/validate

Parameters

Name Required? Type Description
publicToken Yes string The public key of an ongoing payment session.

Example request

await fetch(`https://payment.snipcart.com/api/public/custom-payment-gateway/validate?publicToken=${request.PublicToken}`

GET /payment-session

Returns the ongoing payment session of a customer.

Ressource URL

GET https://payment.snipcart.com/api/public/custom-payment-gateway/payment-session

Parameters

Name Required? Type Description
publicToken Yes string The public key of an ongoing payment session

Example request

await fetch(`https://payment.snipcart.com/api/public/custom-payment-gateway/payment-session?publicToken=${publicToken}`);

Example response

{
  "invoice": {
    "shippingAddress": {
      "name": "Walter",
      "streetAndNumber": "4132  Woodstock Drive",
      "postalCode": "91731",
      "country": "US",
      "city": "El Monte",
      "surname": "C Chapdelaine",
      "region": null
    },
    "billingAddress": {
      "name": "Walter",
      "streetAndNumber": "4132  Woodstock Drive",
      "postalCode": "91731",
      "country": "US",
      "city": "El Monte",
      "surname": "C Chapdelaine",
      "region": null
    },
    "email": "i1p078uft4@powerencry.com",
    "language": "en",
    "currency": "cad",
    "amount": 99.95,
    "targetId": "2f844793-0ce9-4bd6-a54a-698f3af2152c",
    "items": [
      {
        "name": "Starry Night",
        "unitPrice": 79.95,
        "quantity": 1,
        "type": "Physical",
        "discountAmount": 0.0,
        "rateOfTaxIncludedInPrice": 0.0,
        "amount": 79.95
      },
      {
        "name": "Fast shipping",
        "unitPrice": 20.0,
        "quantity": 1,
        "type": "Shipping",
        "discountAmount": 0.0,
        "rateOfTaxIncludedInPrice": 0.0,
        "amount": 20.0
      }
    ]
  },
  "state": "RequiresAuthorization",
  "availablePaymentMethods": [
    {
      "id": "sleeky_pay",
      "flow": "Redirect",
      "name": "SleekyPay",
      "checkoutUrl": "https://sleekypay.example.com/index.html"
    },
    {
      "id": "card",
      "flow": "Form"
    }
  ],
  "id": "b2eb036a-842ee242-0d2d-4fad-bc9a-de16411fc6d1",
  "paymentMethod": "sleeky_pay",
  "paymentAuthorizationRedirectUrl": "https://example.com#/checkout",
  "authorization": {
    "flow": "Redirect",
    "confirmationSynchronicity": "Asynchronous",
    "state": "Unknown",
    "stateDescriptorCode": null,
    "stateDescriptor": null,
    "url": "https://sleekypay.example.com/index.html?publicToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNTgzMTgzMDgwIiwicGF5bWVudFNlc3Npb25JZCI6ImIyZWIwMzZhLTg0MmVlMjQyLTBkMmQtNGZhZC1iYzlhLWRlMTY0MTFmYzZkMSJ9.7LrxV238xcA-d2DuDRBba_8xJC9s9rm8mP6FnukjKVc",
    "card": null
  }
}

POST /payment

The payment endpoint is used to confirm a payment to Snipcart once handled on your end.

Ressource URL

GET https://payment.snipcart.com/api/private/custom-payment-gateway/payment

Headers

Name Value Required? Description
Authorization Bearer <YOUR_SECRET_API_KEY> Yes The authorization request header is used to validate your credentials with the server. Its value must be a bearer token that contains your secret API key.
Content-Type application/json Yes Our API only accepts application/json content type, so you must always specify the application/json content type in each request you make.

body

Name Required? Type Description
paymentSessionId Yes string The ID of the payment session
state Yes string The current state of the payment. Possible values are: processing, processed, invalidated and failed.
error No string An error message you want to display to the customer inside the payment step if applicable.
transactionId Yes string The unique ID of the transaction. The payment gateway often provides this.
instructions No string Additional instructions you want to display to your customer inside the order confirmation screen.
links No object The links object stores utility links for the payment. For instance, you can specify the refund URL using the refunds key.

Example request

await fetch(
  'https://payment.snipcart.com/api/private/custom-payment-gateway/payment', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <YOUR_SECRET_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    paymentSessionId: '<PAYMENT_SESSION_ID>',
    state: '<PAYMENT_STATE>',
    error: '<PAYMENT_ERROR_MESSAGE>',
    transactionId: '<PAYMENT_ID>',
    instructions: 'Your payment will appear on your statement in the coming days',
    links: { refunds: `<YOUR_REFUND_URL>?transactionId=${paymentId}` },
  }),
});

Example response

{
  "returnUrl": "https://example.com?snip-psid=b2eb036a-842ee242-0d2d-4fad-bc9a-de16411fc6d1#/order/2f844793-0ce9-4bd6-a54a-698f3af2152c"
}

Refund webhook

Whenever an order gets refunded through the merchant dashboard, a refund webhook is sent to the refunds URL specified through the /payment endpoint.

Request

Method POST

Content-Type application/json

Body

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

Response

Snipcart expects to receive a JSON object containing the refund ID.

Headers

Name Value Required? Description
Content-Type application/json Yes Our API only accepts application/json content type, so you must always specify the application/json content type in each request you make.

Body

{
 "refundId": "95e32308-b35f-4095-90df-cfab2c5d5ab0"
}