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"

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.

Update settingsUpload your Apple identity so Guardian can generate CSRs, serve the domain-association file, and validate merchant sessions. Provide your `merchant_identifier`, a `display_name`, the byte-exact `domain_association_content` Apple issued, and the `csr_common_name` to embed in generated CSRs. The upload is a partial update: fields you omit keep their current values, and no field is individually required. All four must be set before the dependent flows work. Available only on `self_managed` instances. On Starfish-operated (`sf_operated`) instances the Apple identity and certificates are managed by Starfish, and this endpoint returns `409` with the classifier `APPLE_PAY_CERT_MANAGEMENT_UNAVAILABLE`.

⌘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