ASAP PAY Gateway

Forward requests from ASAP PAY to a target application using a provider URL header. The calling application must either send the gateway public key or come from a whitelisted IP/domain, then send the provider credentials, payload, and request headers itself.

Forward route: /provider

Request Format

Part	Example
Gateway URL	`POST /provider`
Gateway public key	`X-Gateway-Public-Key: d92fd53e0f49c0adca152aea0c32de380c52cb546a5aa4d2883aee36211360f0`
Target URL	`X-Provider-URL: http://127.0.0.1:9090/v1/payments`
Body and auth	Send the exact body and provider auth headers required by the target application.

Example

curl -X POST http://localhost:8080/provider \
  -H "X-Gateway-Public-Key: d92fd53e0f49c0adca152aea0c32de380c52cb546a5aa4d2883aee36211360f0" \
  -H "X-Provider-URL: https://api.provider.com/v1/payments" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-payment-reference" \
  -d '{"amount":1000,"currency":"NGN"}'

Local Mock Provider

Run the included mock provider when you want to test without calling the real provider. It returns the request details it received, with sensitive headers redacted.

MOCK_PROVIDER_PORT=9090 go run ./cmd/provider-mock

For local testing, keep ALLOWED_PROVIDER_HOSTS=127.0.0.1:9090 in .env, then start the gateway.

go run ./cmd/gateway

Then send an ASAP PAY-style request through the gateway.

curl -X POST http://localhost:8080/provider \
  -H "X-Gateway-Public-Key: d92fd53e0f49c0adca152aea0c32de380c52cb546a5aa4d2883aee36211360f0" \
  -H "X-Provider-URL: http://127.0.0.1:9090/v1/payments" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-test-001" \
  -d '{"amount":1000,"currency":"NGN"}'

Response

The gateway returns the target application's status code, safe transport response headers, and response body.

If the public key is missing or invalid and the caller is not whitelisted, the gateway returns 401 with {"error":"invalid gateway public key"}.

Configuration

Env	Current / Default	Purpose
`APP_PORT`	`8080`	HTTP port for this gateway.
`PROXY_PREFIX`	`/provider`	Route prefix used for forwarding.
`GATEWAY_PRIVATE_KEY`	`set`	Private key held by this gateway.
`GATEWAY_PUBLIC_KEY_HEADER`	`X-Gateway-Public-Key`	Header where callers send the gateway public key.
`GATEWAY_WHITELIST`	`not set`	Comma-separated caller IPs, CIDRs, or Origin/Referer domains that can skip the public key.
`PROVIDER_URL_HEADER`	`X-Provider-URL`	Header where ASAP PAY sends the full target URL.
`ALLOWED_PROVIDER_HOSTS`	`not set`	Comma-separated host allowlist. Recommended in production.