Implementing the Snapplify Pay API

This article is for DEVELOPERS and PARTNERS.

With Snapplify’s Pay API, you enable customers across multiple regions to make payments in their local currencies, allowing your business to unlock payments around the world.

Learn more about:

Snapplify Pay’s supported payment methods and currencies
How your customers use Snapplify Pay

Client setup

Credentials must be provided to the client (i.e. you) for implementation. The client credentials are unique per client implementation and are obtained by requesting a product API key from Snapplify.

Client credentials consist of the following values, which will be supplied by Snapplify:

Payment states

A payment state indicates the state of the payment. When your customer’s payment is being processed on Snapplify Pay, it can go through the following states:

Pay endpoints

API and HTTP endpoints are used to integrate with Snapplify Pay. There are three endpoints of which two are API requests and one is an HTTP redirect, as follows:

Payment request

The payment request creates a new payment and returns a token, which is used to submit a payment in subsequent steps. The request must be done from server-to-server and include your unique secret, in addition to the client and other parameters.

Please note: This is a server-to-server call.

Request

POST /payment/request?client=XXX&secret=XXX
Host: pay.snapplify.com
Content-Type: application/json
{ … }

Query string

These query strings are available:

Payment properties

These payment properties are available:

Responses

The response for a successful payment request is as follows:

{
  "token" : "XXXXYYYYZZZZ",
  "redirectUrl" : "https://pay.snapplify.com/payment/submit?token=XXX&client=XXXX"
}

The response for an error is as follows:

{
  "message" : "Invalid client or secret.",
  "code" : 100,
}

The error codes for payment request responses are as follows:

Payment submit

The payment submission with a token from the payment request step will allow your customer to complete their payment. This is a redirect from your store to Snapplify Pay.

Please note: This is a user-to-server call.

Request

GET /payment/submit?client=XXXYYYZZZ&token=XXXYYYZZZ
Host: pay.snapplify.com

Query string

These query strings are available:

Responses

If a payment has been made successfully, Pay will redirect your customer to the *redirectUrl* with the following GET parameters, in addition to any sent on the submit request:

If the payment was declined or there was an error, Pay will redirect your customer to the *declinedUrl* with the following GET parameters, in addition to any sent on the submit request:

The error codes for payment submission responses are as follows:

Payment validation

The payment validation step is not strictly required but we highly recommend its use. The purpose of this API endpoint is to check that the payment is authentic.

A partner or developer may check the payment.referenceCode against the referenceCode sent during the payment request call.

Please note: This is a server-to-server call.

Request

POST /payment/validate?
client=XXXYYYZZZ&secret=XXXYYYZZZ&token=XXXYYYZZZ
Host: pay.snapplify.com

Query String

These query strings are available:

Responses

The response for a successful payment validation is as follows:

{
  "payment": {
    "createdDate": "2018-11-20T13:57:15.000Z",
    "updatedDate": "2018-11-20T15:20:05.000Z",
    "authorisationCode": "ad104788-72d4-444e-9a2e-1325ae1bcc10",
    "referenceCode": "9834538b-26d9-49a2-96a2-55ec81345a81",
    "transactionId": "d993600a-d190-408d-b6c7-49c87b59ab2a",
    "gatewayId": "MOCK",
    "gatewayProvider": "MOCK",
    "completedDate": "2018-11-20T13:57:27.000Z",
    "country": "ZA",
    "currency": "USD",
    "amount": 321.99,
    "paymentMethod": "Credit Card",
    "paymentState": "COMPLETED",
    "errorMessage": null,
    "errorCode": null,
    "validated": true,
    "validatedDate": "2018-11-20T15:20:05.000Z",
    "validatedToken": "e29ae94e-d8c6-4c1f-a927-2543423121c7"
  }
}

The response for an error is as follows:

{
  "message" : "Invalid token, payment or state",
  "code" : 110,
}

The error codes for payment validation responses are as follows:

Learn how to validate the Snapplify Pay IPN.

Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.