Partner API is for Freedom Pay partners: companies that connect their clients to Freedom Pay, open e-money wallets or work with Freedom Pay accounts.
To connect, contact your account manager: Freedom Pay gives you auth_id and a secret key for the signature.
Sign every request: see «Signature».
Method groups#
| Group | What it is for | Signature |
|---|
| Products | Connect a legal entity with a product and create terminals for it. The result contains the merchant ID and the secret key of the client: see Client request status. | X-JWS-Signature |
| E-Money | Open e-money wallets, identify the owner, block and close wallets, get the balance and the statement. | X-JWS-Signature |
| Account | Send payment orders in ISO 20022 format (pain.001) and get their statuses; get the balance and the statement of an account. | X-JWS-Signature |
| Rates | Send currency exchange rates to Freedom Pay. | X-JWS-Signature |
| Invoices | Get the details of an invoice for the payment app that the payer is redirected to. | X-JWS-Signature |
| Implement SuperApp | Register payments and refunds made in a partner super app and get their status. | pg_sig |
Signature#
Methods with paths /v5/partner/… are signed with X-JWS-Signature (HS256): build it as described in «X-JWS-Signature» in Async API Overview. In the JWS header, auth_id is your partner ID; sign with your partner secret key.
For GET methods the request has no body: sign an empty body.
Implement SuperApp methods are signed with pg_sig and the secret key of the merchant: see «Signature» in Merchant API Overview. Sign exactly the bytes of the body you send: a change after signing (formatting, spaces, key order) makes the signature invalid.
Requests processed later#
Methods that create or change data (a client, a terminal, a wallet) accept the request and process it later. Pass a new request_id (UUID) in each such request and get the result with the request status method of the group: Client request status, Product request status, Request Status for wallets.
Errors#
| HTTP | Code | When | What to do |
|---|
200 | status = error with error_code | The request is rejected by business rules. | See error_code and error_description. |
401 | 9998 | The signature is invalid. | Check auth_id, the secret key and the signed body: see «Signature». |
422 | 9403 | The X-JWS-Signature header is missing. | Pass the signature in X-JWS-Signature. |
Support#
If you find an inaccuracy in the documentation or need help with the integration, write to support@freedompay.kz. For connection, contact your account manager.
