API Integration Guide

This guide explains the full API integration flow, from onboarding to getting tokens and making authenticated API requests.

1. Onboarding Process

What is onboarding?

Onboarding is a one-time setup process to obtain your API credentials:

• username
• password
• consumer_key
• consumer_secret

You need an onboarding token provided by Paylov to start this process.

Security Guidelines

Once onboarding is complete, your username and password are set by you, while consumer_key and consumer_secret are issued by Paylov.

Keep all four credentials strictly confidential. Treat them like passwords — never share them, never expose them in client-side code or public repositories, and store them in a secure secrets manager or environment variables.

If your consumer_secret is leaked or exposed to an unauthorized party, notify Paylov support immediately — the credentials will be revoked without delay.

Step 1: Verify onboarding token

First, verify that your onboarding token is valid.

Endpoint

GET {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Parameters

• token required — onboarding token

Example request

# PROD
curl -X GET "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"

Success response 200 OK

{
  "status": "ok"
}

Error response 400 Bad Request

{
  "error": "invalid_or_expired"
}

Step 2: Set username and password

After verifying the token, create your username and password. In return, you will receive your consumer_key and consumer_secret.

Password requirements

Your password must:

• be at least 8 characters long
• contain at least one lowercase letter a-z
• contain at least one uppercase letter A-Z
• contain at least one digit 0-9
• contain at least one special character like !@#$%^&*

Valid password examples

• Secure@Pass123!
• MyP@s3W0rd
• Tr0pic@lLh!eze

Invalid password examples

• password123 — no uppercase and no special character
• Pass123 — too short
• PASSWORD123! — no lowercase letter

Endpoint

POST {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Request headers

Content-Type: application/json

Request body

{
  "username": "...",
  "password": "..."
}

Example request

curl -X POST "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"   
-H "accept: */*"   
-H "Content-Type: application/json"   
-d '{
    "username": "...",
    "password": "..."
  }'

Success response 200 OK

{
  "consumer_key": "app_a1b2c3d4e5f6g7h8i9j0k1",
  "consumer_secret": "Ks8Lp90q0Rr1Ss2Tt3Uu4Vv5Ww6Xx7Yy8Zz9Aa0Bb1Cc2Dd3Ee",
  "username": "my_username"
}

Important notes

• consumer_key and consumer_secret are your API credentials. Store them securely.
• consumer_secret is shown only once. If you lose it, you need to create new credentials.
• The onboarding token can only be used once.
• Keep your username and password safe.

---

2. Obtaining Access Token

What is an access token?

An access token is required for authenticated API requests. Include it in every API call.

Token request process

Endpoint

POST {BASE_URL}/merchant/oauth2/token/

Authentication

Use Basic Authentication by encoding your consumer_key and consumer_secret in base64 format.

Request headers

Authorization: Basic base64(consumer_key:consumer_secret) # YycX3bGtsMnJfWH...
Content-Type: application/json

Request body

{
    "grant_type": "password",
    "username": "some-username",
    "password": "strong-password"
}

Step 1: Prepare Basic Authorization

Combine your consumer key and consumer secret in this format:

consumer_key:consumer_secret

Then encode that value to base64.

Step 2: Send token request

Example request

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/"   
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>"   
-H "Content-Type: application/json"   
-d "grant_type=password&username=my_username&password=secure_password_123"

Success response 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_abc123def456ghi789jkl012mno345pqr",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800
}

Response explanation

• access_token — token for API requests, valid for 1 hour
• refresh_token — token used to get a new access token, valid for 7 days
• expires_in — access token lifetime in seconds
• refresh_expires_in — refresh token lifetime in seconds

Error response 401 Unauthorized

{
  "error": "invalid_grant",
  "error_description": "Invalid credentials or this account not activated"
}

---

3. Making API Requests with Access Token

Using access token

Include the access token in the Authorization header of every API request.

Header format

Authorization: Bearer YOUR_ACCESS_TOKEN

Example request

curl -X GET "https://{BASE_URL}/merchant/status/"   # example endpoint
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

---

4. Refreshing Access Token

When your access token expires, use the refresh token to obtain a new one. You do not need to send username and password again.

Endpoint

POST {BASE_URL}/merchant/oauth2/token/

Request headers

Authorization: Basic base64(consumer_key:consumer_secret)
Content-Type: application/json

Request body

{
"grant_type": refresh_token,
"refresh_token": "refresh_abc123def456ghi789jkl012mno345pqr"
}

Example request

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/"   
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>"   
-H "Content-Type: application/json"   
-d "grant_type=refresh_token&refresh_token=refresh_abc123def456ghi789jkl012mno345pqr"

Success response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_xyz789abc123def456ghi789jkl012mno",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800
}

---

5. Revoking Tokens

You can revoke a token to prevent it from being used further.

Endpoint

POST {BASE_URL}/merchant/oauth2/revoke/

Request headers

Content-Type: application/json

Request body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Example request

curl -X POST "https://{BASE_URL}/merchant/oauth2/revoke/"   
  -H "Content-Type: application/json"   
  -d '{
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Success response 200 OK

{
  "status": "success"
}

---

6. Error Handling

400 Bad Request

{
  "error": "invalid_request",
  "error_description": "Basic authorization header required"
}

Cause:

Authorization header is missing or malformed.

401 Unauthorized

{
  "error": "invalid_grant",
  "error_description": "Invalid credentials"
}

Cause:

Username, password, consumer key, or consumer secret is incorrect.

400 Invalid or Expired Token

{
  "error": "invalid_or_expired"
}

Cause:

Token has expired or is invalid. Obtain a new token.

---

7. Quick Reference

API endpoints

Method	Endpoint	Purpose
GET	/merchant/onboard	Verify onboarding token
POST	/merchant/onboard	Complete onboarding
POST	/merchant/oauth2/token/	Get or refresh access token
POST	/merchant/oauth2/revoke/	Revoke a token

Error codes

Error	Description
invalid_request	Request is malformed
invalid_client	Consumer key is invalid
invalid_grant	Credentials are invalid
unsupported_grant_type	Grant type not supported
invalid_or_expired	Token is invalid or expired
token_required	Token parameter is missing