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:


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:


NameValueAdditional notes
nameStringA display label for the client
clientStringUnique client identifier
secretStringUnique private key
emailStringA client's email address


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:


Payment StateDescriptionDefault
NEWThe payment has not been charged.Yes
ERRORThe payment is in an error state.No
COMPLETEDThe payment has been completed successfully.No


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:


Live endpointhttps://pay.snapplify.com
API requests/payment/request

/payment/validate

HTTP redirect
/payment/submit


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:


NameValueRequiredAdditional notes
clientStringYesUnique client code
secretStringYesPrivate key


Payment properties


These payment properties are available:


Parameter nameValueRequiredAdditional notes
referenceCodeStringNo

Unique code supplied by the client

notificationUrlStringNoFuture-proofing; IPN endpoint
redirectUrlStringYesCan include extra get vars
declinedUrlStringNoCan include extra get vars
cancelUrlStringNoCan include extra get vars
backUrlStringNoCan include extra get vars
amountDoubleYes0.00
currencyStringYesISO 4217 alphabetic code
countryStringYesISO 3166-1 alpha-2


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:


CodeMeaning
100Invalid client or secret
101Invalid parameter
109Reference code already in use
500Internal error


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:


NameValueRequiredAdditional notes
clientStringYesUnique client code
tokenStringYesThe token that was returned in the payment request call.


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:


NameValue
clientString
tokenString
successInt (always 1)
referenceCodeString


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:


NameValue
clientString
tokenString
successInt (always 0)
errorCode

Int

errorMessageString
referenceCodeString


The error codes for payment submission responses are as follows:


CodeMeaning

100

Invalid client or secret

110

Invalid token, payment, or state

111

Payment error

112

Payment declined

501

Gateway error (the error message will hold additional error information)


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:


NameValueRequired

client

StringYes
secret
String
Yes
token
String

Yes


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:


Code
Meaning

100

Invalid client or secret

110

Invalid token, payment, or state



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.