Pay to Merchant Documentation

Version: 1.0

Person-to-Merchant (P2M) integration allows a consumer to pay a merchant directly through the Cashia API using mobile money. This guide covers end-to-end implementation — from merchant authentication to callback verification — ensuring secure, traceable, and performant transactions.

Environment Configuration

Review the shared Environment Setup guide for sandbox merchant identifiers, currency defaults, and base URLs. Use those values (or your assigned production credentials) when constructing the requests that follow.

1. Overview

2. Authentication


curl --location 'https://staging.cashia.com/api/v1/authorization' \
  --header 'Content-Type: application/json' \
  --data '{
    "login": "[email protected]",
    "password": "your_password"
}'

Step 2: Validate Merchant OTP

Use static OTP 534789 in staging environment.


curl --location 'https://staging.cashia.com/api/v1/authorization/confirm' \
  --header 'Content-Type: application/json' \
  --data '{
    "login": "[email protected]",
    "otp": "534789"
}'

3. Creating a Point of Sale (POS)

Only needed once to create terminalId.


curl --location 'https://staging.cashia.com/api/v1/points-of-sale' \
  --header 'Authorization: Bearer [yourBearerToken]' \
  --header 'Content-Type: application/json' \
  --data '{
    "categoryId": "bc0fe4b9-fa4a-441d-aebd-ecffbfd5bfad",
    "posCompanyName": "YourCompanyName",
    "description": "Your Company Description",
    "website": "https://your-website-url.com",
    "resultUrl": "https://your-callback-url.com/webhook",
    "serverUrl": "https://your-server-url.com/api",
    "trustAllCertificates": true,
    "terminalId": "terminal-abc123",
    "merchantId": "019a06ee-a28c-760a-9d82-669be5c04ddc"
  }'

4. Initiating a Payment Request


curl --location 'https://h32de16gy8.execute-api.eu-west-1.amazonaws.com/api/public/v1/merchant-payments' \
  --header 'Content-Type: application/json' \
  --header 'X-Cashia-Hash: yourHash' \
  --header 'X-Cashia-Signature: yourSignature' \
  --header 'X-Cashia-Timestamp: yourTimestamp' \
  --header 'X-Cashia-Key-ID: yourApiKey' \
  --header 'X-Cashia-Nonce: yourNonceToken' \
  --data '{
    "terminalId": "terminal-abc123",
    "currency": "KES",
    "amount": 5,
    "merchantStika": "KES_123456",
    "orderId": "order-12345",
    "description": "Payment for order #12345",
    "payer": { 
      "method": "phone", 
      "value": "254712345678" 
    },
    "urls": {
      "callbackUrl": "https://your-callback-url.com/webhook",
      "successRedirectUrl": "https://your-website-url.com/success"
    }
  }'

5. Checking Payment Status


curl --location 'https://h32de16gy8.execute-api.eu-west-1.amazonaws.com/api/public/v1/merchant-payments/status' \
  --header 'X-Cashia-Hash: yourHash' \
  --header 'X-Cashia-Signature: yourSignature' \
  --header 'X-Cashia-Timestamp: yourTimestamp' \
  --header 'X-Cashia-Key-ID: yourApiKey' \
  --header 'X-Cashia-Nonce: yourNonceToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentIdentifier": "the-payment-identifier"
  }'

6. Generating Secure Headers (HMAC-SHA256)

Follow the shared Authentication & HMAC Guide to generate the nonce, timestamp, body hash, and signature used across P2M calls. The exact same header format applies to endpoints in this section.

7. Troubleshooting

Issue	Possible Cause	Resolution
401 Unauthorized	Expired/invalid token	Re-authenticate merchant
403 Forbidden	Bad signature	Regenerate headers; verify timestamp/nonce
404 Not Found	Invalid endpoint or POS ID	Confirm URL and terminal registration
422 Unprocessable Entity	Malformed payload	Validate JSON structure
429 Too Many Requests	Rate limit hit	Apply exponential back-off
500 Server Error	Internal error	Retry later / contact support

8. Test Checklist

Step	Scenario	Expected Result
0	Check Email for Merchant Credentials and generate API Secret and Key	API Secret and Key
1	Login with merchant credentials	Bearer token received
2	Validate OTP (534789)	Session activated
3	Create POS terminal	Terminal ID returned
4	Initiate payment (registered payer)	Status pending
5	Initiate payment (unregistered payer)	Status no_user
6	Accept scenario	Status paid
7	Decline scenario	Status declined
8	Expiry scenario	Status expired
9	Get status by identifier	Correct transaction state
10	Callback delivery	POST received by merchant

Support

Need escalation? Visit Support & Troubleshooting for contact channels and the checklist of information to include in your ticket.