API reference

Forwarding

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a ForwardingRequest

POST/v1/forwarding/requests

Creates a ForwardingRequest object.

Body parameters

  • payment_methodstringRequired

    The PaymentMethod to insert into the forwarded request. Forwarding previously consumed PaymentMethods is allowed.

  • replacementsarray of stringsRequired

    The field kinds to be replaced in the forwarded request.

  • urlstringRequired

    The destination URL for the forwarded request. Must be supported by the config.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • requestobject

    The request body and headers to be sent to the destination endpoint.

    Show 2 child parameters
    • bodystring
    • headersarray of objects
      Show 2 child parameters
      • namestringRequired
      • valuestringRequired

Returns

The forwarding.request object.

POST /v1/forwarding/requests
curl https://api.knoxapi.com/v1/forwarding/requests \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d payment_method=pm_456 \
  -d "replacements[]=card_cvc" \
  -d url=https://endpoint-url/v1/payments
Response
{
  "created": 1234567890,
  "id": "fwdreq_123",
  "livemode": false,
  "object": "forwarding.request",
  "payment_method": "pm_456",
  "replacements": [],
  "request_context": {
    "destination_duration": 234,
    "destination_ip_address": ""
  },
  "request_details": {
    "body": "'{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"cvc\": \"***\",\"expiryMonth\": \"03\",\"expiryYear\": \"2030\",\"holderName\": \"First Last\",\"number\": \"************4242\",\"type\": \"scheme\",},\"merchantAccount\":\"{{MERCHANT_ID}}\",\"reference\":\"{{REFERENCE_ID}}\"}'",
    "headers": [
      {
        "name": "Idempotency-Key",
        "value": "{{UPSTREAM_IDEMPOTENCY_KEY}}"
      }
    ],
    "http_method": "POST"
  },
  "response_details": {
    "body": "'{\"transactionId\":\"example1234\"}'",
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json;charset=UTF-8"
      },
      {
        "name": "Idempotency-Key",
        "value": "{{UPSTREAM_IDEMPOTENCY_KEY}}"
      }
    ],
    "status": 200
  },
  "url": "https://endpoint-url/v1/payments"
}

List all ForwardingRequests

GET/v1/forwarding/requests

Lists all ForwardingRequest objects.

Query parameters

  • createdobject

    Similar to other List endpoints, filters results based on created timestamp. You can pass gt, gte, lt, and lte timestamp values.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    A pagination cursor to fetch the previous page of the list. The value must be a ForwardingRequest ID.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A pagination cursor to fetch the next page of the list. The value must be a ForwardingRequest ID.

Returns

A list of forwarding.request objects.

GET /v1/forwarding/requests
curl -G https://api.knoxapi.com/v1/forwarding/requests \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/forwarding/requests",
  "has_more": false,
  "data": [
    {
      "created": 1234567890,
      "id": "fwdreq_123",
      "livemode": false,
      "object": "forwarding.request",
      "payment_method": "pm_456",
      "replacements": [],
      "request_context": {
        "destination_duration": 234,
        "destination_ip_address": ""
      },
      "request_details": {
        "body": "'{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"cvc\": \"***\",\"expiryMonth\": \"03\",\"expiryYear\": \"2030\",\"holderName\": \"First Last\",\"number\": \"************4242\",\"type\": \"scheme\",},\"merchantAccount\":\"{{MERCHANT_ID}}\",\"reference\":\"{{REFERENCE_ID}}\"}'",
        "headers": [
          {
            "name": "Idempotency-Key",
            "value": "{{UPSTREAM_IDEMPOTENCY_KEY}}"
          }
        ],
        "http_method": "POST"
      },
      "response_details": {
        "body": "'{\"transactionId\":\"example1234\"}'",
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json;charset=UTF-8"
          },
          {
            "name": "Idempotency-Key",
            "value": "{{UPSTREAM_IDEMPOTENCY_KEY}}"
          }
        ],
        "status": 200
      },
      "url": "https://endpoint-url/v1/payments"
    }
  ]
}

Retrieve a ForwardingRequest

GET/v1/forwarding/requests/{id}

Retrieves a ForwardingRequest object.

Path parameters

  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The forwarding.request object.

GET /v1/forwarding/requests/{id}
curl https://api.knoxapi.com/v1/forwarding/requests/fwdreq_123 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "id": "fwdreq_123",
  "livemode": false,
  "object": "forwarding.request",
  "payment_method": "pm_456",
  "replacements": [],
  "request_context": {
    "destination_duration": 234,
    "destination_ip_address": ""
  },
  "request_details": {
    "body": "'{\"amount\":{\"value\":1000,\"currency\":\"usd\"},\"paymentMethod\":{\"cvc\": \"***\",\"expiryMonth\": \"03\",\"expiryYear\": \"2030\",\"holderName\": \"First Last\",\"number\": \"************4242\",\"type\": \"scheme\",},\"merchantAccount\":\"{{MERCHANT_ID}}\",\"reference\":\"{{REFERENCE_ID}}\"}'",
    "headers": [
      {
        "name": "Idempotency-Key",
        "value": "{{UPSTREAM_IDEMPOTENCY_KEY}}"
      }
    ],
    "http_method": "POST"
  },
  "response_details": {
    "body": "'{\"transactionId\":\"example1234\"}'",
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json;charset=UTF-8"
      },
      {
        "name": "Idempotency-Key",
        "value": "{{UPSTREAM_IDEMPOTENCY_KEY}}"
      }
    ],
    "status": 200
  },
  "url": "https://endpoint-url/v1/payments"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.