Download OpenAPI specification:Download
API contract for external payment integrations.
Third-party integrators implement this API as a standalone REST service. LoyaltyPlant (payments-service) calls these endpoints to delegate payment operations to your integration; your service in turn talks to your PSP (payment service provider). You never call payments-service to run a payment — payments-service drives the flow by calling you.
Settle (capture) funds previously held by /v1/authorize. Requires the
CAPTURE capability. transactionReference is the value you returned
from authorize. amount is optional — omit it to capture the full
authorized amount, or pass a smaller value for a partial capture.
Idempotent on Idempotency-Key.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
| Idempotency-Key required | string <uuid> UUID for idempotent request handling, unique per logical operation. Carried by all mutating operations (authorize, sale, capture, refund, reverse); the read-only operations (inquire-status, capabilities, health) do not carry it. Your integration MUST return the same response for repeated requests carrying the same key (payments-service retries transient/network failures and must never double-charge). |
| paymentId required | string Unique payment identifier from payments-service |
| transactionReference required | string Transaction reference you returned from authorize |
| amount | number Capture amount (optional, for partial capture; if omitted, captures the full authorized amount) |
object Partner/outlet-specific configuration provisioned by LoyaltyPlant (NOT chosen by the integrator) |
{- "paymentId": "8e2b7d6a-1f3c-4e9a-9c2b-77a0e3d4f111",
- "transactionReference": "psp_txn_7Hagain2",
- "amount": 49.99,
- "settings": {
- "currency": "USD"
}
}{- "status": "SUCCESS",
- "transactionReference": "psp_txn_7HagaIn2"
}Authorize and capture in a single call (single-phase payment).
payments-service calls this when your integration declares the SALE
capability. Return SUCCESS with a transactionReference, PENDING +
redirectUrl for 3DS/redirect (see the integrationResult callback),
or DECLINED/RETRIABLE/UNKNOWN. Idempotent on Idempotency-Key.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
| Idempotency-Key required | string <uuid> UUID for idempotent request handling, unique per logical operation. Carried by all mutating operations (authorize, sale, capture, refund, reverse); the read-only operations (inquire-status, capabilities, health) do not carry it. Your integration MUST return the same response for repeated requests carrying the same key (payments-service retries transient/network failures and must never double-charge). |
| paymentId required | string Unique payment identifier from payments-service |
| amount required | number Payment amount in major currency units (e.g. 49.99). Convert to your PSP's required unit yourself. |
| currency required | string ISO 4217 currency code (e.g. "USD", "EUR", "SAR") |
object Partner/outlet-specific configuration provisioned by LoyaltyPlant
(NOT chosen by the integrator). Common keys: |
{- "paymentId": "8e2b7d6a-1f3c-4e9a-9c2b-77a0e3d4f111",
- "amount": 49.99,
- "currency": "USD",
- "settings": {
- "currency": "USD",
- "merchantId": "acct_3092f1"
}
}{- "status": "SUCCESS",
- "transactionReference": "psp_txn_7HagaIn2"
}{- "status": "SUCCESS",
- "transactionReference": "psp_txn_7HagaIn2"
}Return funds for a captured payment. Requires the DIRECT_REFUND
capability. transactionReference identifies the original payment;
amount is the amount to refund (supports partial refunds).
Idempotent on Idempotency-Key.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
| Idempotency-Key required | string <uuid> UUID for idempotent request handling, unique per logical operation. Carried by all mutating operations (authorize, sale, capture, refund, reverse); the read-only operations (inquire-status, capabilities, health) do not carry it. Your integration MUST return the same response for repeated requests carrying the same key (payments-service retries transient/network failures and must never double-charge). |
| paymentId required | string Unique payment identifier from payments-service |
| transactionReference required | string Transaction reference of the payment to refund |
| amount required | number Refund amount in major currency units (supports partial refunds) |
| reason | string Reason for the refund (free text, for your records / PSP) |
object Partner/outlet-specific configuration provisioned by LoyaltyPlant (NOT chosen by the integrator) |
{- "paymentId": "8e2b7d6a-1f3c-4e9a-9c2b-77a0e3d4f111",
- "transactionReference": "psp_txn_7Hagain2",
- "amount": 10,
- "reason": "Item out of stock",
- "settings": {
- "currency": "USD"
}
}{- "status": "SUCCESS",
- "transactionReference": "psp_txn_7HagaIn2"
}Void an authorization before it is captured (releases the hold).
transactionReference is the value returned from authorize.
Idempotent on Idempotency-Key.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
| Idempotency-Key required | string <uuid> UUID for idempotent request handling, unique per logical operation. Carried by all mutating operations (authorize, sale, capture, refund, reverse); the read-only operations (inquire-status, capabilities, health) do not carry it. Your integration MUST return the same response for repeated requests carrying the same key (payments-service retries transient/network failures and must never double-charge). |
| paymentId required | string Unique payment identifier from payments-service |
| transactionReference required | string Transaction reference of the payment to reverse/void |
object Partner/outlet-specific configuration provisioned by LoyaltyPlant (NOT chosen by the integrator) |
{- "paymentId": "8e2b7d6a-1f3c-4e9a-9c2b-77a0e3d4f111",
- "transactionReference": "psp_txn_7Hagain2",
- "settings": {
- "currency": "USD"
}
}{- "status": "SUCCESS",
- "transactionReference": "psp_txn_7HagaIn2"
}Queries the PSP for the current status of a previously initiated payment.
Used for reconciliation and manual status checks (e.g. after a timeout or
an UNKNOWN result, or when an async callback never arrived).
Requires STATUS_POLLING capability. This is a read-only operation and
carries no Idempotency-Key.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
| transactionReference | string Transaction reference returned by a previous authorize/sale/capture operation |
| paymentId | string Payment ID from payments-service (alternative lookup key) |
{- "transactionReference": "psp_txn_7Hain2",
- "paymentId": "8e2b7d6a-1f3c-4e9a-9c2b-77a0e3d4f111"
}{- "status": "CAPTURED",
- "transactionReference": "psp_txn_7HagaIn2",
- "rawStatus": "captured"
}Returns the list of payment capabilities this integration supports. Payments-service caches the result and validates capabilities before invoking optional operations — it will never call an operation whose capability you did not declare. Declare only what you have actually implemented and tested.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
{- "capabilities": [
- "CAPTURE",
- "DIRECT_REFUND",
- "REDIRECT_FLOW",
- "DIRECT_WEBHOOK",
- "STATUS_POLLING"
]
}Returns the health status of the integration service.
Payments-service polls this endpoint periodically to decide whether to
route traffic to your integration. Return DOWN (or 503) when your
PSP connection is unavailable so payments-service can stop sending you
live payments until you recover.
| Authorization required | string Bearer token authenticating payments-service to your integration (the outbound token LoyaltyPlant provisions for you during onboarding). Validate it on every request (constant-time compare) and reject anything else with 401. Treat the token as a secret; rotate it via LoyaltyPlant. Example: "Bearer sk_live_abc123". |
{- "status": "UP"
}