Yapstone APIs for Hosted Payments - 29-09-2025 15:16 (1.0.274)

Throughout this document the following terms are used:

• Hosted Payment Page The page hosted by Yapstone that is used to collect payment information from the payer.
• Merchant The entity that is collecting payments from the payer.
• Payer The entity that is making a payment to the merchant.
• Order A time limited session created by the merchant on the Yapstone platform to collect payment information from the payer.
• Sandbox. An integration environment provided by Yapstone which offers a similar API experience to the production environment, but all payment events are simulated.

The Yapstone Hosted Payments API allows a merchant to redirect the paying customer to a Yapstone-hosted payment page to collect payment information. The API also allows the merchant to receive notifications of payment events. The workflow is as as follows:

• The payer completes the checkout process on the merchant website
• The merchant back end server sends a request to the Yapstone Hosted Payments API to create an order
• The response from the Yapstone Hosted Payments API contains a URL that the merchant can redirect the payer to
• The payer is redirected to the Yapstone-hosted payment page and enters their payment information
• The payment information is sent to the Yapstone Hosted Payments API and the payment is processed
• The payer is redirected back to the merchant website
• A notification is sent to the merchant back end server to inform them of the payment event

The Yapstone Hosted Payments API is REST based and uses the JSON format for requests and responses. The API uses standard HTTP status codes to indicate the success or failure of an API request.

Following is a list of Http Status codes that could be returned by the platform

| Status Code            | Description                                                                          |
| -----------------------| -------------------------------------------------------------------------------------|
| 200 OK                 | The request was successfully processed and usually returns a json response           |
| 204 OK                 | The request was successfully processed and no content is returned                    |
| 400 Bad Request        | The request is invalid and should be fixed before retrying                           |
| 401 Unauthorized       | Authentication has failed                                                            |
| 404 Not Found          | The resource was not found                                                           |
| 5xx Server Error       | Platform internal error (should rarely happen)                                       |

The Yapstone Hosted Payments API uses webhooks to notify the merchant of payment events.

The merchant can configure the URL of their webhook endpoint when they create an order using the create order API.

The Yapstone Hosted Payments API will send a POST request to the merchant webhook endpoint when a payment event occurs. The request will contain a JSON payload with information about the payment event.

You must include a shared secret when creating a webhook

The platform will use the secret as the key when generating a signature

The signature is a HMAC hex digest using the sha256 hash function and the secret as the HMAC key

The message is the payload of the webhook

The signature is included in the request header as Webhook-Signature

The merchant should verify the signature by generating a signature using the same secret and comparing it to the signature in the request header

If the signatures match, the request is valid and can be processed

An example of how to verify the signature in Node.js is shown below:

const crypto = require('crypto');

// The payload in the webhook
const payload = {
  "eventDate" : "2024-04-02T10:28:09.363847Z",
  "orderId" : "7dbc18a6-63ce-4ffe-afbe-becdb271bfa4",
  "orderStatus" : "ACTIVE",
  "paymentType" : "CARD",
  "paymentAmount" : {
     "value" : 2141,
     "currency" : "USD"
  },
  "referenceNumber" : "1pGh5LJRa2Go9LprMj9f",
  "billingAddress" : {
     "line1" : "34 High Lane",
     "city" : "BOSTON",
     "countyOrProvince" : "MA",
     "zipOrPostcode" : "02114-3411",
     "country" : "US"
  }
};

// Secret key
const secretKey = '<The signingKey provided when creating the order>';

// Convert JSON payload to a string
const payloadString = JSON.stringify(payload);

// Generate SHA-256 HMAC signature
const signature = crypto.createHmac('sha256', secretKey)
.update(payloadString)
.digest('hex');

console.log("SHA-256 Signature:", signature);

The platform will retry sending the webhook with an exponential backoff for up to 48 hours if the merchant server does not respond with a 2xx status code

The platform supports idempotency for the following APIs:

• Create Order

The idempotency key is a unique identifier for the request that is provided by the merchant. It is included in the request header as Idempotency-Key. The key can be any string value and should be unique for each request. It is recommended to use a UUID. The platform will return the same response for the same request if the same idempotency key is used

Hosted Payments Service Operations