Guides
Payments API Migration (UAE)
Map legacy UAE payment endpoints to the current Spare API.
Who this is for
This guide is for existing UAE integrations moving from the legacy payment endpoints to the current API. New integrations should start from Quick Start Setup and don't need this page.
Global changes
| Legacy | Current | |
|---|---|---|
| Sandbox base URL | https://sandbox.tryspare.ae | https://api.sandbox.tryspare.ae |
| Tenant header | - | x-tenant: UAE on every request (except JWKS) |
Authentication signatures and request-body structures are unchanged unless noted below.
Authentication
| Operation | Legacy | Current | Change |
|---|---|---|---|
| Token | GET /api/v1.0/authentication/Token | POST /auth/api-keys/sessions | Method GET → POST; status 200 → 201 |
| Refresh | GET /api/v1.0/authentication/Refresh | POST /auth/api-keys/sessions/refresh | Method GET → POST |
| JWKS | GET /api/v1.0/authentication/Jwks | GET /auth/.well-known/jwks.json | No auth or tenant header |
The refresh token may be sent as the refresh-token header or in the body as { "refreshToken": "..." }.
Providers & purpose codes
| Operation | Legacy | Current |
|---|---|---|
| Purpose codes | GET /api/v1.0/pis/Common/ListPurposeCodes | GET /payment-purpose-codes |
| List providers | GET /api/v1.0/pis/Provider/List | GET /providers |
Payment requests
| Operation | Legacy | Current | Change |
|---|---|---|---|
| Create | POST /api/v1.0/pis/Request/Initiate | POST /payment-requests | Status 200 → 201 |
| Fetch | GET /api/v1.0/pis/Request/Fetch/{refId} | GET /payment-requests/{refId} | - |
| List | - | GET /payment-requests?page=1&perPage=20 | New |
| Delete | - | DELETE /payment-requests/{paymentRequestId} | New |
Consent
| Operation | Legacy | Current | Change |
|---|---|---|---|
| Create (optional) | POST /api/v1.0/pis/Consent/Create?id={refId} | POST /consent/payment/create?id={refId} | Status 200 → 201 |
| Get | GET /api/v1.0/pis/Consent/Get?consentId={id}&providerName=... | GET /consent/payment/{consentId} | consentId moved to path; providerName removed |
| Sync | GET /api/v1.0/pis/Consent/Sync?paymentRequestId={id} | GET /consent/payment/sync?paymentRequestId={id} | - |
| List | - | GET /consent/payment/list?page=1&perPage=20 | New |
Payments
| Operation | Legacy | Current | Change |
|---|---|---|---|
| Get | GET /api/v1.0/pis/Payment/Get?paymentId={id} | GET /payments/{paymentId} | paymentId moved to path |
| Write / callback (optional) | POST /api/v1.0/pis/Payment/Write?code=...&state=... | POST /payment-actions/write-callback?code=...&state=... | Status 200 → 201 |
Confirmation of Payee
| Operation | Legacy | Current |
|---|---|---|
| Confirm (optional) | POST /api/v1.0/pis/ConfirmationOfPayee/Confirm?providerId={id} | POST /payment/cop?providerId={id} |
What changed, in short
TokenandRefreshare nowPOST, notGET.- Create / write operations return
201instead of200. - Path parameters replace query parameters for
consentIdandpaymentId. providerNameis dropped from consent lookup.- Every request carries
x-tenant: UAE, except JWKS.
Key takeaways
- The base URL moves to
https://api.sandbox.tryspare.aeand every request (except JWKS) needsx-tenant: UAE. - Most changes are path/method/status; request bodies and auth signatures are unchanged.
- New list/delete endpoints exist for payment requests and consents.