Callbacks

The most important parts of Payment Initiation API (e.g. Payment initiation) are asynchronous.

Every Web application has to provide a set of valid URLs which we will use to notify about the payment progress. Other applications can poll Payment Initiation API in order to retrieve the current payment status.

There are several common points about the request we send to the callback URLs provided by the client:

  • The Content-Type header is application/json;
  • There is a Signature header that identifies the request was signed by Payment Initiation API;
  • The request method is always POST;
  • The JSON object sent will always have a data field;
  • The meta field will display the version of the callbacks API.

You can set the callback URLs for your application by accessing your Payment Initiation tab on the callbacks page.

Due to security reasons, the callbacks can be sent to ports 80/HTTP (in test and pending modes) and 443/HTTPS (in test, pending and live modes) only!
Also, the callbacks not follow redirects!

Signature

In order for the client to identify that the request is coming from Payment Initiation API, there is a Signature header in the request.

Signature - base64 encoded SHA256 signature of the string represented in the form callback_url|post_body - 2 parameters concatenated with a vertical bar |, signed with a Payment Initiation API’s private key. You can find the version of the signature key used to sign the callback in the Signature-key-version header. The current version is 4.0 which corresponds to the following public key:

  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzi1XL1b0XwUYVHj7/AR6
  Hr0YN34wH/bDOIub0nwt0s/s3tD+DPxNB85xpMEZrLikPW5PAKkQ/oC3OyPYxKOb
  8TNhzGmQhEfyCkbdRwxNZqRMRwuOc+N4sdBtQKPN8+XF3RIcRZAk25JGROtb1M2o
  d/Nb9QqdQwMjdk6W+Vdq5Sj25Tj2efJc8zmBJkNXR4WtW45p4XSdjSEjuVCSZjOy
  +N8/Od8MGixC99jYbiKm3RrVDJCgDi4YYnNRI0QgxZRpJKbQX/WeZiYOrbctG3m8
  l1/Hpkv3w1QHz/YFIshCOKwUL+xg1hLMaW4IH7XFHenE+JlUKdCqhcWyi7oIDkyr
  7wIDAQAB
  -----END PUBLIC KEY-----

An example of the string that is to be used to generate the signature looks as follows:

https://www.client.com/api/payments/callbacks/success|{"data":{"payment_id":"1234","customer_id":"4321","custom_fields":{},"status": "processing"},"meta":{"version":"1","time":"2017-01-03T13:00:28Z"}}

The pseudocode that we use to generate the signature looks like this:

base64(sha256_signature(private_key, "callback_url|post_body")))

Success

We send a callback to your application’s success URL whenever an operation has caused a change in the data we store for a particular payment.

For instance, after you’ve redirected your user to the Connect page and they have selected their provider, gave their consent and pressed Pay, we’ll send you a success callback. This callback will contain the customer identifier, the ID of the newly created payment and its status. Afterwards, your application will be able to use the show payment route and query the information about this payment.

Whenever we have more information about the payment, we will send another success callback.

A success callback marks a change in the data and you can generally expect from one to three success callbacks with the same payload within several minutes. We recommend that your application fetch the full payment data at each callback, as some information might change during the fetching process.

For instance, when your user has initiated a payment using Salt Edge Connect, we will send the following success callback:

{
  "data": {
    "payment_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2018-10-22T10:50:41.982Z"
  }
}

You can now use the show payment route and obtain the provider and some other attributes of the new payment.

Failure

Sometimes a payment will fail to go through. It might happen because the interactive data was not sent by the user, provider access was not granted or we could not perform one of the steps of the payment process. In this case, you will receive a fail callback, containing a JSON similar to the following:

{
  "data": {
    "payment_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "status": "rejected",
    "error_class": "ProviderAccessNotGranted",
    "error_message": "Provider access was not granted"
  },
  "meta": {
    "version": "1",
    "time": "2018-10-22T10:50:41.982Z"
  }
}

After you get this callback, you need to request the payment to check for its updates. Please note that even if there’s an error, we still store the payment.

Notify

After a new payment was created in the payment initialization process, Salt Edge can inform you about the progress the payment is going through using a Notify callback.

Your app can expect the notify callback several times, but you can use this information to inform your user about what’s happening with their payment.

The possible stages sent in a notify callback are described here.

Note that for some of the payments, you might not receive all the stages.

Here’s an example callback sent to the /notify route of your app:

{
  "data": {
    "payment_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "submission",
    "status": "processing"
  },
  "meta": {
    "version": "1",
    "time": "2018-10-21T10:50:41Z"
  }
}