Wallet Tokens

Forward wallet token

Forward a request to a certified third-party provider with the wallet token’s card data injected server-side, so it never touches your systems. This mirrors Forward card data and Forward cryptogram.

The available placeholders depend on the token’s auth_method:

CRYPTOGRAM_3DS: {{ dpan }}, {{ cryptogram }}, {{ eci }}, {{ expiry_month }}, {{ expiry_year }}. The cryptogram is single-use — the token is consumed by the first successful forward.
PAN_ONLY: {{ fpan }}, {{ expiry_month }}, {{ expiry_year }}. Forwardable repeatedly.

Using a placeholder the token’s auth_method does not carry returns 422 with the classifier DESTINATION_POLICY_VIOLATION; a declared placeholder without a value on this specific token returns 422 with PLACEHOLDER_VALUE_MISSING. Forwarding an already-consumed CRYPTOGRAM_3DS token returns 400 with CRYPTOGRAM_CONSUMED.

See Wallet Tokens for details.

POST

api

wallet

{id}

forward

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/{id}/forward \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-destination-url: <x-destination-url>' \
  --data '
{
  "paymentMethod": {
    "type": "networkToken",
    "number": "{{ dpan }}",
    "expiryMonth": "{{ expiry_month | unwrap }}",
    "expiryYear": "{{ expiry_year | unwrap }}"
  },
  "mpiData": {
    "authenticationResponse": "Y",
    "cavv": "{{ cryptogram }}",
    "eci": "{{ eci }}"
  }
}
'

{}

{
  "code": 400,
  "message": "The request could not be handle due to invalid data",
  "classifier": "BAD_REQUEST"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 404,
  "message": "The requested resource was not found.",
  "classifier": "NOT_FOUND"
}

{
  "code": 422,
  "classifier": "VALIDATION_ERROR",
  "message": "Validation error",
  "validation_errors": [
    {
      "path": "json-path",
      "message": "human readable error message"
    }
  ]
}

{
  "code": 502,
  "message": "Bad gateway",
  "classifier": "BAD_GATEWAY"
}

{
  "code": 503,
  "message": "Service unavailable",
  "classifier": "SERVICE_UNAVAILABLE"
}

{
  "code": 504,
  "message": "Gateway timeout",
  "classifier": "GATEWAY_TIMEOUT"
}

Authorizations

Authorization

string

header

required

JWT bearer token obtained via the OAuth2 client-credentials grant from the platform Authentication API. The token's scopes gate the endpoints it may call, and its audience names the Guardian instance. This is the standard way to authenticate to Guardian.

Headers

x-destination-url

string<uri>

required

The target URL to which the request shall be forwarded. Guardian forwards calls only to whitelisted destination URLs (major payment providers are included by default). Contact support to whitelist a custom URL.

Example:

"https://api.psp.example.com/payments"

x-own-header-name

string

Name of a header to set on the forwarded request. Guardian strips the credential your call authenticates with (for example x-api-key) before forwarding; use this pair to send the destination's own credential instead. Only takes effect together with x-own-header-value.

Example:

"x-api-key"

x-own-header-value

string

Value for the header named by x-own-header-name, set on the forwarded request — typically your credential for the destination.

Example:

"sk_live_51Hxxxx"

Path Parameters

string<uuid>

required

The ID of the wallet token to forward.

Body

application/json

The payload to forward to the third-party provider.

Use placeholders to inject the wallet token's card data on the fly. Append | unwrap to emit a value as its native type instead of a string, e.g. {{ expiry_month | unwrap }}.

Response

Success response

The response from the third-party provider.

⌘I

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/{id}/forward \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-destination-url: <x-destination-url>' \
  --data '
{
  "paymentMethod": {
    "type": "networkToken",
    "number": "{{ dpan }}",
    "expiryMonth": "{{ expiry_month | unwrap }}",
    "expiryYear": "{{ expiry_year | unwrap }}"
  },
  "mpiData": {
    "authenticationResponse": "Y",
    "cavv": "{{ cryptogram }}",
    "eci": "{{ eci }}"
  }
}
'

{}

{
  "code": 400,
  "message": "The request could not be handle due to invalid data",
  "classifier": "BAD_REQUEST"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 404,
  "message": "The requested resource was not found.",
  "classifier": "NOT_FOUND"
}

{
  "code": 422,
  "classifier": "VALIDATION_ERROR",
  "message": "Validation error",
  "validation_errors": [
    {
      "path": "json-path",
      "message": "human readable error message"
    }
  ]
}

{
  "code": 502,
  "message": "Bad gateway",
  "classifier": "BAD_GATEWAY"
}

{
  "code": 503,
  "message": "Service unavailable",
  "classifier": "SERVICE_UNAVAILABLE"
}

{
  "code": 504,
  "message": "Gateway timeout",
  "classifier": "GATEWAY_TIMEOUT"
}

Getting Started

Tokens

Metadata

Admin

Forward wallet token

Authorizations

Headers

Path Parameters

Body

Response