Introduction

Test data

Card	Bank	Mobile
Pan 5438898014560229	9040003019246	233551946046
Cvv 789	300318 (STANBIC BANK)	MTN
Expiry 09/19	GHS test bank account	GHS test mobile money
Pin 3310
Otp 12345

Payment methods for countries

Currency	Card	Bank	Mobile
XOF	+	-	+
XAF	+	-	+

Country phone codes

Country	Currency	Code
ML	XOF	+223
SN	XOF	+221
CI	XOF	+225
CM	XAF	+237

Request parameters

Request headers

Key	Value	Description	Type
Authorization	Bearer token	User authorization by token	string
version	336	Last mobile app version	number

Request body

The data listed in the table for the request is sent to the body of the request

Query parameters

The data listed in the table for the request is sent in the format:

https://host.com/api/endpoint?key=value

Authentication

Send confirmation code by SMS

Sample answer:

{
  "success": true,
  "resendDelay": 30
}

HTTP Request

POST /auth/send-verification-code

Request body

Parameter	Type	Description
web	bool	Flag whether sent from the web (optional, default false)
phone	string	Telephone
country	string	Country code (example: "CI")

Login

В if the request is successful:

{
  "token": "token_here" //JWT token,
  "user": {...}
}

HTTP Request

POST /auth/login

Request body

Parameter	Type	Description
phone	string	Telephone
code	string	Verification code

Users

Complete registration

Sample answer:

{
  "success": true,
  "user": {...}
}

We have to check the user object every time after login. If user.isRegistred === false, go to the completion screen and make this request

HTTP Request

PUT /users/registration

Auth token: required

Request body

Parameter	Type	Description
email	string	email address
firstName	string	Name
lastName	string	Surname
picture	string	Avatar (optional)

Get user

Sample answer:

{
  "user": {...}
}

HTTP Request

GET /users/me

Auth token: required

Edit user information

Sample answer:

{
  "success": true,
  "user": {...}
}

HTTP Request

PUT /users/me

Auth token: required

Request body

Parameter	Type	Description
email	string	email address
firstName	string	Name
lastName	string	Surname
company	string	Company (optional)
picture	string	Avatar (optional)

Search for users

Sample answer:

{
  "result": []
}

HTTP Request

GET /users/search

Auth token: required

Query parameters

Parameter	Description
search	Substring for searching by phone / first / last name (minimum 3 characters)

Get user by id

Sample answer:

{
  "user": {}
}

HTTP Request

GET /users/:id

Auth token: required

Upgrade subscription plan

Sample answer:

{
  "success": true
}

An example of an error:

{
  "error": true,
  "errorMessage": "Insufficient funds on wallet"
}

HTTP Request

POST /users/update-account-type

Auth token: required

Request body

Parameter	Type	Description
subscriptionPlan	ObjectID	ID of the new subscription plan

Get verification status

Sample answer:

{
  "success": true,
  "veriffStatus": "APPROVED",
  "rejectReason": null,
  "idPicture": "https://cloudinary.com/picture.png",
  "documentPicture": "https://cloudinary.com/document.png"
}

If a veriffStatus === APPROVED, verification process completed

HTTP Request

GET /users/verification

Auth token: required

Query parameters

Parameter	Description
force	Needed to start a new verification process, bool

Invite user

Sample answer:

{
  "success": true,
  "user": {...}
}

HTTP Request

Also used to create a new account when transferring money for a user who is not yet in the system (the isInvite flag in this case isfalse)

POST /users/invite

Auth token: required

Request body

Parameter	Type	Description
phone	string	Telephone

Add device token (iOS)

Sample answer:

{
  "success": true
}

HTTP Request

POST /users/add-token/ios

Request body

Parameter	Type	Description
token	string	Device token

Add device token (Android)

Sample answer:

{
  "success": true
}

HTTP Request

POST /users/add-token/android

Request body

Parameter	Type	Description
token	string	Device token

Remove device token (iOS)

Sample answer:

{
  "success": true
}

HTTP Request

POST /users/remove-token/ios

Request body

Parameter	Type	Description
token	string	Device token

Delete device token (Android)

Sample answer:

{
  "success": true
}

HTTP Request

POST /users/remove-token/android

Request body

Parameter	Type	Description
token	string	Device token

Get user by phone number

Sample answer:

{
  "success": true,
  "user": {
    ...
  }
}

HTTP Request

GET /users/phone/:phone

Wallets

Topup a wallet

Sample answer:

{
  "success": true,
  "authurl": "..." // redirect link
}

HTTP Request

POST /wallets/top-up

Auth token: required

Request body

Parameter	Type	Description
amount	number	Amount
phone	string	The phone number from which you want to top up
network	string	mobile network (optional)

Transferring money to another wallet

Sample answer:

{
  "success": true
}

An example of an error:

{
  "error": true,
  "errorMessage": "Insufficient funds on wallet"
}

HTTP Request

POST /wallets/transfer

Auth token: required

Request body

Parameter	Type	Description
amount	number	The amount you want to transfer
recipient	ObjectID	Recipient ID
message	string	Commentary on the transaction (Optional)

Get wallet balance

Sample answer:

{
  "data": {
    "balance": 1000,
    "currency": "XOF",
    "phone": "",
    ...
  }
}

HTTP Request

GET /wallets/balance

Auth token: required

Get wallet statistics

Sample answer:

{
  "overall": [],
  "month": [],
  "year": []
}

HTTP Request

GET /wallets/statistic

Auth token: required

Get wallet top-up methods

Sample answer:

{
  "paymentMethods": ["card", "mobile"],
  "isCardForm": false
}

Possible method types: card, mobile

HTTP Request

GET /wallets/topup-payment-methods

Auth token: required

Get user wallet transactions

Sample answer:

{
  "count": 0,
  "transactions": []
}

Possible transaction types: top-up, transfer, withdraw, subscription-payment, card-payment, card-fund, card-refund, card-transfer, card (includes all card-types)

HTTP Request

GET /wallets/transactions

Auth token: required

Query parameters

Parameter	Description
page	Page in request
limit	Limit of returned transactions in a request
type	Transaction type

Get methods of withdrawing money from the wallet

Sample answer:

{
  "paymentMethods": ["mobile", "bank"],
  "form": "phone"
}

Possible values for paymentMethods: mobile, bank

Possible values form: mobile, bank

HTTP Request

GET /wallets/withdraw-payment-methods

Auth token: required

Money withdrawal

Sample answer:

{
  "success": true
}

An example of an error:

{
  "error": true,
  "errorMessage": "Insufficient funds on wallet"
}

HTTP Request

POST /wallets/withdraw

Auth token: required

Request body

Parameter	Type	Description
amount	number	Amount
phone	string	Phone number for withdrawal. Regulars: /^+225\d{10}$/ - country CI, /^+237\d{9}$/ - country CM, /^+221\d{9}$/ - country SN, /^+223\d{8}$/ - country ML

Invoices

Create invoice

Sample answer:

{
  "success": true,
  "invoice": {...}
}

HTTP Request

POST /invoices

Auth token: required

Request body

Parameter	Type	Description
amount	number	Amount
recipient	ObjectID	Recipient ID
message	string	Comment
dueDate	string	Date, format: "2018-05-20T00:00:00.000Z"

Get a list of sent invoices

Sample answer:

{
  "count": 0,
  "invoices": []
}

User Sent Invoices

Possible invoice statuses: expired, rejected, pending, paid

HTTP Request

GET /invoices/sent

Auth token: required

Query parameters

Parameter	Description
page	Page in request
limit	Limit of returned invoices in request
status	Invoice status

Get a list of received invoices

Sample answer:

{
  "invoices": []
}

Инвойсы, которые получил пользователь

HTTP Request

GET /invoices/received

Auth token: required

Reject invoice

Sample answer:

{
  "success": true
}

HTTP Request

GET /invoices/:id/reject

Auth token: required

Pay invoice

Sample answer:

{
  "success": true
}

An example of an error:

{
  "error": true,
  "errorMessage": "Insufficient funds on wallet"
}

HTTP Request

GET /invoices/:id/pay

Auth token: required

Get the number of invoices received

Sample answer:

{
  "count": 0
}

HTTP Request

GET /invoices/received-count

Auth token: required

Get complete invoice information

Sample answer:

{
  "recipient": {
    "id": "5b087a843951f8354e9304ac",
    "picture": "https://res.cloudinary.com/payqin-ltd/image/upload/w_150,h_150,c_thumb,g_face/jusxlpa6h0s8n9xtbvzl.jpg",
    "firstName": "...",
    "lastName": "...",
    "phone": "+22507********",
    "currency": "XOF",
    "country": "CI",
    "company": null,
    "phoneFormat": {
      "prefix": "225",
      "lengthAfterPrefix": null
    }
  },
  "sum": {
    "fee": 2.6572787899999994,
    "amount": 19.909292999999998,
    "rateValue": 5.575296,
    "targetAmount": 111,
    "targetCurrency": "XOF",
    "fullAmount": 22.566571789999998
  }
}

HTTP Request

GET /invoices/:id/transfer-info

Auth token: required

Resources

Get QR code in png format

Answer in the format image/png

HTTP Request

GET /resources/qr-code

Auth token: required

Get QR code in pdf format

Answer in the format application/pdf

HTTP Request

GET /resources/qr-code-pdf

Auth token: required

Get a link for payment

Sample answer:

{
  "link": "http://188.166.94.104/p/5ad31a3fb216fd2cfe1ab696"
}

HTTP Request

GET /resources/pay-link

Auth token: required

Get user from payment link

Sample answer:

{
  "success": true,
  "user": {...}
}

HTTP Request

POST /resources/decode-link

Auth token: required

Request body

Parameter	Type	Description
link	string	The payment link that the user clicked on

Get card types

Sample answer:

{
  "cardTypes": []
}

Used when creating a new map

HTTP Request

GET /resources/card-types

Auth token: required

Convert currencies

Sample answer:

{
  "success": true,
  "result": 15.00
}

HTTP Request

POST /resources/convert

Auth token: required

Request body

Parameter	Type	Description
amount	number	Amount
sourceCurrency	string	Currency from which we convert
targetCurrency	string	Currency we convert to

Cards

Create card

Sample answer:

{
  "success": true,
  "card": {
    "id": "cbbbdf9f-bc8e-495f-9898-8c3e3ed582f0",
    "AccountId": ...,
    "amount": "5.00",
    "currency": "USD",
    "card_hash": "...",
    "cardpan": "...",
    "maskedpan": "...",
    "city": "...",
    "state": "...",
    "address_1": "...",
    "address_2": null,
    "zip_code": "...",
    "cvv": "...",
    "expiration": "2025-06",
    "send_to": null,
    "bin_check_name": null,
    "card_type": "visa",
    "name_on_card": "...",
    "date_created": "2021-06-22T13:24:16.7037289+00:00",
    "is_active": true,
    "callback_url": null,
    "pin": null,
    "is_virtual": null
  }

An example of an error:

{
  "error": true,
  "errorMessage": "Insufficient funds on wallet"
}

HTTP Request

POST /cards

Auth token: required

Request body

Parameter	Type	Description
cardType	ObjectID	ID card type

Fund card

Sample answer:

{
  "success": true
}

An example of an error:

{
  "error": true,
  "errorMessage": "Insufficient funds on wallet"
}

HTTP Request

POST /cards/:id/fund

Auth token: required

Request body

Parameter	Type	Description
amount	number	Amount

Freeze card

Sample answer:

{
  "success": true
}

HTTP Request

GET /cards/:id/freeze

Auth token: required

Unfreeze card

Пример ответа:

{
  "success": true
}

HTTP Request

GET /cards/:id/unfreeze

Auth token: required

Delete card

Sample answer:

{
  "success": true
}

HTTP Request

DELETE /cards/:id

Auth token: required

Get a list of cards

Sample answer:

{
  "cards": [{
    ...,
    "is_active": true //true - card is not frozen, false - frozen
  }]
}

HTTP Request

GET /cards

Auth token: required

Business

Get a business transaction

Sample answer:

{
  "success": true,
  "transaction": {
    "id": "5b6b4d356fda8b2eddce695c",
    "merchant": {
      "id": "5b6304c7aa39ed2e9f396974",
      "picture": null,
      "firstName": "Name",
      "lastName": "Surname",
      "phone": "+22501222222",
      "currency": "XOF",
      "country": "CI",
      "company": null,
      "phoneFormat": {
        "prefix": "225",
        "lengthAfterPrefix": 8
      }
    },
    "currency": "XOF",
    "amount": 534,
    "status": "open",
    "orderNumber": null,
    "customerNumber": null
  }
}

HTTP Request

GET /business/transaction/:id

Pay for business transaction

Пример ответа:

{
  "success": true, // может быть false
  "redirectUrl": "..."
}

After paying for the transaction, you need to redirect the user to redirectUrl

HTTP Request

GET /business/transaction/:id/pay

Auth token: required

Get a merchant

Sample answer:

{
  "success": true,
  "merchant": {
    ...
  }
}

HTTP Request

GET /business/merchant

Auth token: required

Update merchant

Sample answer:

{
  "success": true,
  "merchant": {
    ...
  }
}

HTTP Request

PUT /business/merchant

Auth token: required

Request body

Parameter	Type	Description
fee	number	Commission percentage
checkOrderUrl	string	Link to check the correctness of the order
notifyUrl	string	Link for notifications about the end of order processing
successUrl	string	Link where we redirect in case of a successful transaction
failUrl	string	Link to redirect to in case of unsuccessful transaction
link	string	Merchant's unique link

Check link for uniqueness

Sample answer:

{
  "success": true,
  "isLinkUnique": true
}

HTTP Request

POST /business/merchant/check-link

Auth token: required

Request body

Parameter	Type	Description
link	string	Merchant's unique link

Generate a new secret key

Sample answer:

{
  "success": true,
  "merchant": {
    "secretKey": "...",
    ...
  }
}

HTTP Request

GET /business/merchant/generate-key

Auth token: required

Get a list of merchant transactions

Sample answer:

{
  "success": true,
  "transactions": [{
    ...
  }]
}

HTTP Request

GET /business/transactions

Auth token: required

Add vendor

Sample answer

{
  "success": true,
  "merchant": {
    ...
  }
}

HTTP Request

POST /business/merchant/vendor

Auth token: required

Request body

Parameter	Type	Description
payqinId	string	Vendor ID in the main system
name	string	Vendor store name

Errors

PayQin API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.