Snipcart API Endpoints

The base url for the custom payment gateway API is https://payment.snipcart.com/api

Validate public token

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

This is important to prevent fraudulent payments
When calling your API, we will always send a publicToken. Use this endpoint to validate the request was made by our API.
This token should always be validated to prevent fraudulent attempts.

Request

publicTokenstring - Required
The public key of an ongoing payment sessions.

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

Retrieve a payment session

GET /public/custom-payment-gateway/payment-session?publicToken=<SOME_TOKEN>
Retrieves the payment session from the publicToken.

Request

publicTokenstring - Required
The public key of an ongoing payment sessions.

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

Response

idGuid
The payment session's Id.

invoiceInvoice
The session's invoice

paymentAuthorizationRedirectUrlstring
The url to redirect to once the checkout flow is completed.

{
  "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",
}

Create payment

POST /private/custom-payment-gateway/payment
Creates a payment for the payment session (confirms the payment)

Request

Headers
Authorizationstring - Required
Bearer <YOUR_SECRET_API_KEY> 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-Typestring - Required
application/json Our API only accepts application/json content type, so you must always specify the application/json content type in each request you make.

Body
paymentSessionIdstring - Required
The ID of the payment session

state"processing" | "processed" | "invalidated" | "failed" - Required
The current state of the payment. Possible values are: processing, processed, invalidated and failed.

transactionIdstring - Required
The unique ID of the transaction. The payment gateway often provides this.

errorError Represents the error message you want to display to the customer inside the payment step if applicable.

Error
codestring - Required
This is used to used to localize the message in the cart.
messagestring
This is used as a fallback when no match is found for code

instructionsstring
Additional instructions you want to display to your customer inside the order confirmation screen.

linksLinks

The `links` object stores utility links for the payment. For instance, you can specify the refund URL using the `refunds` key.

Links
refundsstring This will be called when a refund is issued via the merchant dashboard

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"
        }
}'

Your webhooks

Those are the API endpoints you will need to create to integrate your own Payment gateway. Our API will call them with a publicToken in the request body.
Don't forget to validate the request by using the /validate endpoint

Payment methods

The first important endpoint your API should have is one returning the available payment methods. When a client checkouts, we will call your API endpoint to show them the available payment methods.

We will send a POST request to the payment method URL specified in the merchant dashboard.

We expect to receive an array of PaymentMethod.

Request

Method POST

Body
invoiceInvoice
The invoice of the current order

publicTokenstring
Used to validate the request was made by Snipcart

mode"test" | "live"
The order's mode.

{
  "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"
}

Response

Body
PaymentMethods[] - Required
The available payment methods for the current order.

PaymentMethod
idstring - Required
This is the id of the payment method.

namestring - Required
The name of the payment method (this will be shown during the checkout phase)

checkoutUrlstring - Required
The url of your checkout page.

iconUrlstring
If you'd like to show an icon instead of a name during the checkout phase, you can set it here.

Note that only the name or the icon will be shown, not both

{
  "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"
    }
  ]
}

Refund

This is the refund endpoint you can provide when confirming the payment with our api. When refunding a client from the merchant dashboard, this endpoint will be called.

Request

Method POST

Body
paymentIdstring
The payment we want to refund.

amountnumber
The amount to want to refund.

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

Response

refundIdGuid
The id of the refund.

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

Types

Invoice

shippingAddressAddress
The order's shipping address.

billingAddressAddress
The order's billing address.

emailstring
The client's email address.

languagestring
The cart's language.

currencystring
The order's currency.

amountnumber
The order's grand total.

targetIdGuid
The cart's ID

itemsItem[]
The order's items.

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

Address

namestring
Recipient's full name (first name and last name)

streetAndNumberstring
Street and civic street number.

postalCodestring

countrystring

citystring

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

Item

namestring

unitPricenumber
The price of the item

quantitynumber

type"Physical" | "Digital" | "Tax" | "Shipping" | "Discount"
Represents the item type.

rateOfTaxIncludedInPricenumber

amountnumber
The quantity * unitPrice

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

Snipcart API Endpoints

Your webhooks

Types

Was this article helpful?