Skip to main content

Forward API Requests

Cards tokenized with Stitch can be used to initiate payment operations with multiple payment service providers using the Stitch API. When a request is submitted with a token, the API retrieves the associated credentials, adds them to the request, and then forwards the enriched request to the third-party API.

Token selectors—placeholder strings used in the request—indicate which values should be substituted with the sensitive data stored in Vault.

Integration Overview​

Request Forwarding is protected by a client token. You'll need to follow the steps described in the client token guide to obtain a client token with the client_vault_proxy scope.

The Stitch REST API URL https://api.stitch.money/v2/forwarded-requests can be used for forwarding requests to downstream providers.

Payment Initiation​

To initiate a payment using a token stored in Stitch Vault, you must first create a token that securely represents the card details. This token can then be used in conjunction with Stitch Relay to route the payment request to a third-party payment service provider, without exposing sensitive data to your systems. This approach ensures PCI compliance while maintaining flexibility in how and where payments are processed.

Requests​

Initiate a POST request to to forward a request:

curl -X POST 'https://api.stitch.money/v2/tokens' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
      "token": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
      "timeout": 60000,
      "destinationRequest": {
        "url": "https://api.psp-example.com/v1/payments",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json",
          "Authorization": "Bearer PSP_ACCESS_TOKEN"
        },
        "body": "{\"amount\":10000,\"currency\":\"ZAR\",\"card\":{\"number\":\"{{card.number}}\",\"expiryMonth\":\"{{card.expiry.month}}\",\"expiryYear\":\"{{card.expiry.year}}\"},\"reference\":\"INV-10001\"}"
      }
  }'
FieldTypeDescription
tokenstringThe identifier for the stored card token in Vault. Used to retrieve and inject sensitive data.
timeoutnumber (optional)Maximum time (in milliseconds) to wait for the proxied request to complete. The maximum configurable timeout is 120,000 ms (120 seconds).
securityCodestring (optional)CVV associated with the card. Required by some PSPs; not stored with the token in Vault.
request.urlstringThe destination URL of the third-party API to which the request will be proxied.
request.methodstringThe HTTP method to use when making the proxied request.
request.bodystringThe body of the request to be sent to the third-party API as a JSON or raw string.
request.headersobjectHTTP headers to include in the proxied request

Stitch will return a response with a status of either success or failure. The status indicates if the request forwarding was successful or not i.e. the request was proxied to the destination API and a response was received. The id returned in the response is unique to each forwarded request.

Error Handling

Use the failure.reason field in responses with status failure to handle errors that occur while attempting to connect to the downstream provider.

For example, Stitch may return a failure response with a failure.reason of timeout if the request exceeds the default or custom timeout value.

Downstream Response Handling

A response with status success is returned if the request was successfully forwarded to the destination API. The result depends on how the destination API handled the request. The response.status field contains the HTTP status code returned by the downstream resource. Use this field to handle errors such as 400 Bad Request or 500 Internal Server Error.

For example, the API may return a success response with a response.status of 400, indicating that the request was forwarded to the specified destination, but the destination rejected it due to invalid input.

{
  "id": "2b2aa9ba-1f41-44e5-8292-923149bf225d",
  "token": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
  "request": {
    "url": "https://api.psp-example.com/v1/payments",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer PSP_ACCESS_TOKEN"
    },
    "body": "{\"amount\":10000,\"currency\":\"ZAR\",\"card\":{\"number\":\"{{card.number}}\",\"expiryMonth\":\"{{card.expiry.month}}\",\"expiryYear\":\"{{card.expiry.year}}\"},\"reference\":\"INV-10001\"}"
  },
  "status": "success",
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"id\":\"959488dd-b225-42b4-b2ba-f9d779c70641\",\"status\":\"SUCCESS\"}"
  }
}

Token Selectors​

Token selectors are placeholder strings used to identify which sensitive data elements associated with a stored token should be substituted into the proxied request body. These placeholders allow dynamic injection of secure data without exposing raw credentials or identifiers. The table below enumerates the supported selectors.

SelectorDescription
{{card.number}}Substitutes the full encrypted card number (PAN)
{{card.expiry}}Substitutes the card's expiry in MM/YY format
{{card.expiry.month}}Substitutes only the expiry month of the card
{{card.expiry.year}}Substitutes only the expiry year of the card
{{card.securityCode}}Substitutes the card’s security code (CVV/CVC)

Destination Allowlisting​

Destination URLs must be allowlisted before requests can be forwarded to a downstream API. Please contact support@stitch.money for assistance with this configuration.

Sandbox Testing​

The Forward Request API can be tested by initiating requests using a Test Client. The table below outlines the scenarios that can be simulated in the Sandbox environment using specific timeout values.

TimeoutDescription
1.1success result with 400 response code
2.1failure result
-success result with 200 response code