Ecommerce Integration Document

Introduction
This document describes the Integration between

SantimPay and ecommerce websites. The main expected
feature is enabling the different bank users to pay online
from the ecommerce site.
We have prepared, explained, and illustrated well-defined

use cases for each point of integration to ecommerce sites.
Testing and production URL, Private key, Gateway token will
be shared on the integration group.
Confidentiality
Confidentiality All information contained in this document
shall be kept in confidence. No part of this document is to
be altered or copied without the written agreement made
with SantimPay.
Security requirement
1. The ecommerce site shall provide Private key before go
live
2. JWT sign
About SantimPay
SantimPay Financial Solutions SC is formed under the
National Bank of Ethiopia’s Payment System Proclamation
No- 718/2011, to serve as a payment system operator in
Ethiopia.
SantimPay provides POS, UPI wallet, Payment Gateway, and

other payment solutions to banks and end-users.
Since its inception, SantimPay has been excited to provide

its clients with trailblazing innovative products continuously
and within our 3-Year journey in R&D, we have been
expanding to meet customers' standards and work
hand-in-hand towards the satisfaction of banks.
Workflow
Create check out session in NodeJS
Demo projects are attached with this documentation.
demo languages are :-
1. NodeJS
2. PHP
3. Java
4. and .Net
Data organization
JWT Sign method
Generate payment URL

generate payment url is handled by sending POST JSON
request to:-
https://services.santimpay.com/api/v1/gateway/initiate-payment
Note:- Gateway token shall be provide on the header as bearer token
Key data type description
id int client transaction id ,

transaction id is
generated by the
e-commerce system
reason string the ecommerce site

provides intended service
description and will be
displayed to payer on
payment page
merchantId string merchantId will be provide

by SantimPay
signedToken string Signed token is encrypted

payload with the private
key, as described on the
signing process
successRedirectUrl string The ecommerce successful

payment customer page,
after the successful
payment the gateway
redirects the user to this
link
failureRedirectUrl string The ecommerce failed

payment customer page,
after the failed payment
the gateway redirects the
user to this link
notifyUrl string Call backURL , Ecommerce

site shall prepare POST
endpoint that will be hit
after transaction.
Sample callback/webhook request

{
"txnId": "d7fa8146-cb58-405a-8ca7-920cdc1f56da",
"created_at": "2023-02-28T10:26:17.904879Z",
"updated_at": "2023-02-28T10:26:49.042602Z",
"thirdPartyId": "1",
"merId": "f660f84e-7395-417b-91ff-542026c38326",
"merName": "santimpay test company",
"address": "Addis Ababa",
"amount": "1",
"currency": "ETB",
"reason": "Payment for a coffee",
"msisdn": "",
"accountNumber": "",
"paymentVia": "Telebirr",
"refId": "5e4af4cc-99d1-4db9-a784-4ba4eb75e646",
"successRedirectUrl": "https://santimpay.com",
"failureRedirectUrl": "https://santimpay.com",
"message": "payment successful",
"status": "COMPLETED",
"receiverWalletID": ""
}
Callback anti-forgery validation

The callback header includes signedToken signed with the Private key provided
by the merchant.
The merchant shall validate the header signedToken value with the public-key
before operation on the response.
Header value for signedToken = Signed-Token
B2C (Withdrawal) operation
SantimPay provides multiple B2C options through the partners, B2C transactions
are realtime and will be deducted from the merchant escrow/deposit balance.
To get all SantimPay B2C partners use ➖

Get method on public API
http://services.santimpay.com/api/v1/gateway/payout/partners
The response should look like this
To transfer B2C to a specific customer , the merchant should send one of the
partner id and receiver customer phone-number or bank account number.
https://services.santimpay.com/api/v1/gateway/payout-transfer
{
"amount":0.5,
"clientReference":"123675xcdx03",
"id":"123675uiuiouoi03",
"merchantId":"9e2dab64-e2bb-4837-9b85-d855dd878d2b",
"paymentMethod":"Telebirr",
"reason":"BUY GOODS",
"receiverAccountNumber":"+251932118929",
"signedToken":"eyJhbGciOiJFUzI1NiJ9.eyJhbW91bnQiOjEwMDAwLCJwYXltZW50U
mVhc29uIjoiQlVZIEdPT0RTIiwibWVyY2hhbnRJZCI6IjllMmRhYjY0LWUyYmItNDgzNy05
Yjg1LWQ4NTVkZDg3OGQyYiIsImdlbmVyYXRlZCI6MTY4MDE4NTAzM30.V26LbOxQ8
QbOvHJ1bVz4zOcoqnN5GiaYtv0Yn4K6pj-S6Xij2wIRzlCH6ssaFkEO3xQjOeKEuzVfU9
2Oh90I6g"
}
Error response on B2C

Successful Transfer
{
"txnId": "a1d3dce6-5ffe-4bb9-b0f4-c1e57dd4bb63",
"created_at": "2023-04-07 08:08:48.127080706 +0000 UTC",
"updated_at": "2023-04-07 08:08:48.127080706 +0000 UTC",
"thirdPartyId": "123675uiuiouoi03",
"merId": "9e2dab64-e2bb-4837-9b85-d855dd878d2b",
"merName": "Santimpay Test Company",
"address": "Addis Ababa",
"amount": "0.5",
"currency": "ETB",
"reason": "BUY GOODS",
"reciverPhoneNumber": "+251932118929",
"reciverAccountNumber": "",
"paymentVia": "Telebirr",
"clientReference": "123675xcdx03",
"message": "Succesfully debited from your wallet account.",
"status": "SUCCESS"
}
Phone number format error
{
"message": "phone number must be in the format +251912345678",
"status": "declined"
}
Balance more that user’s balance

{
"message": "ERROR: new row for relation \"santimpay_wallets\" violates check
constraint \"chk_santimpay_wallets_balance_is_non_negative\" (SQLSTATE
23514)",
}
Payment method not supported (Wrong partner ID)

{
"message": "Payment Method Not Supported",
}
Invalid token / Wrong token generation

{
"message": "Invalid token",
}
wrong key signing

{
"message": "crypto/ecdsa: verification error",
}
Duplicate client reference
{
"message": "Duplicate Client Reference.",
}

Ecommerce Integration Document

Uploaded by

Copyright:

Available Formats

Ecommerce Integration Document

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ecommerce Integration Document

Uploaded by

Copyright:

Available Formats

Introduction

This document describes the Integration between

We have prepared, explained, and illustrated well-defined

SantimPay provides POS, UPI wallet, Payment Gateway, and

Since its inception, SantimPay has been excited to provide

Generate payment URL

Note:- Gateway token shall be provide on the header as bearer token

Key data type description

id int client transaction id ,

reason string the ecommerce site

merchantId string merchantId will be provide

signedToken string Signed token is encrypted

successRedirectUrl string The ecommerce successful

failureRedirectUrl string The ecommerce failed

notifyUrl string Call backURL , Ecommerce

Sample callback/webhook request

Callback anti-forgery validation

To get all SantimPay B2C partners use ➖

The response should look like this

Error response on B2C

Balance more that user’s balance

Payment method not supported (Wrong partner ID)

Invalid token / Wrong token generation

wrong key signing

You might also like