This documentation presents the procedure for integrating digital payment solutions into your e-commerce platform. The different resources available:
\nTest authentication
\nCreate a bill
\nGet bill's details
\nGet bill's list
\nGet available payments gateways
\nCallback Url
\nEnvironement: Sandbox
Endpoint: https://sandbox.semoa-payments.com/api
CashPay uses HTTP status codes to indicate success or failure of API calls. Status codes in the 2xx range indicate success, 4xx range indicate error in the information provided, and 5xx range indicate server side errors. The following table lists some commonly used HTTP status codes.
\nIn the rest of this document, the following abbreviations will be used.
\nIn version 2.0 we have impement a new type of authentication with Oauth2, but you can also use Cashpay Authentication.
\nOur APIs uses the OAuth 2.0 protocol for authentication/authorization. All access to our APIs requires authentication. Authenticated requests require an access_token.
\nThe security of Cashpay Api with this type of authentication is carried by 4 parameters in the headers of the request: login, apireference, salt and apisecure.
\nBelow the description :
\nNB: For each request you must generate an identifier (salt) which will be an unique integer. This will make your request unique to the API.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"General presentation","slug":"general-presentation"},{"content":"Access to API:","slug":"access-to-api"},{"content":"Errors","slug":"errors"},{"content":"Abbreviations","slug":"abbreviations"}],"owner":"4377470","collectionId":"fa7a575e-a752-42ba-ae66-65d193481d3d","publishedId":"UUxukWRR","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-09-22T15:55:55.000Z"},"item":[{"name":"Authentication","item":[{"name":"ping","event":[{"listen":"prerequest","script":{"id":"0639065f-6d37-4657-9bbd-05cdb0984835","exec":["function getApiSecure()","{"," var login = environment.login;"," var apiKey = environment.api_key;"," var salt = Date.now();"," var some = login + apiKey + salt;"," var apiSecure = CryptoJS.SHA256(some).toString();"," var result = {};"," result.api_secure = apiSecure;"," result.salt = salt;"," return result;","}","","var data = getApiSecure();","","postman.setEnvironmentVariable('api_secure', data.api_secure);","postman.setEnvironmentVariable('salt', data.salt);"],"type":"text/javascript"}},{"listen":"test","script":{"id":"31334038-21f9-49b8-ae95-8d972ae2fcc0","exec":["pm.test(\"response is ok\", function(){"," pm.response.to.have.status(201);","});",""],"type":"text/javascript"}}],"id":"aeb8e80c-1d56-4413-a63a-e221bc9766d2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"login","value":"{{login}}"},{"key":"apisecure","value":"{{api_secure}}"},{"key":"apireference","value":"{{api_reference}}"},{"key":"salt","value":"{{salt}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n\t\"action\": \"ping\"\n}"},"url":"{{endpoint}}/ping","description":"This resource allow you to test authentication to the API
\nInput Parameters:
\nOutput Parameters:
\nThis operation is used to generate an access token which can then be used to authorize and authenticate towards the other end-points of the API.
\nNB: For all resources, you must send in headers parameters a Authorization Token Bearer.
\nRESPONSE
\nThis resource is used to get payment's gateways available for a specific merchant account
\nResponse :
\nPayment's method types:
\n","urlObject":{"path":["gateways"],"host":["{{endpoint}}"],"query":[],"variable":[]}},"response":[{"id":"73fff68e-8c7a-40fe-a228-cebb48dd5976","name":"Gateways list with OAuth2","originalRequest":{"method":"GET","header":[{"key":"login","value":"{{login}}","disabled":true},{"key":"apisecure","value":"{{api_secure}}","disabled":true},{"key":"apireference","value":"{{api_reference}}","disabled":true},{"key":"salt","value":"{{salt}}","disabled":true},{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPV2pmTktHcVl5b2VFd2FNV0d1UFNTdkZaVW5jVjc1aUtDLXMxMjRQZThJIn0.eyJleHAiOjE3MDA2NjY3NzEsImlhdCI6MTcwMDY2MzE3MSwianRpIjoiY2M1MjBiNTEtYjI2ZS00NzcwLWI1YjktMmNkOGZhMDQ2YmRmIiwiaXNzIjoiaHR0cHM6Ly9sb2NrLnNlbW9hLWhvc3RpbmcuY29tL3JlYWxtcy9EZXYuZW52IiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImM3YjVhODNhLTYyNjctNGY2MC1iODZkLTdiMTcwYjIwZGRjZCIsInR5cCI6IkJlYXJlciIsImF6cCI6ImNhc2hwYXkiLCJzZXNzaW9uX3N0YXRlIjoiY2ZhYjg5OWQtN2E0MS00YTk5LWE1NzUtZTVkNWJmZDRiNWViIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIqIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLWRldi5lbnYiLCJST0xFX1VTRVIiLCJvZmZsaW5lX2FjY2VzcyJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicm9sZXMgb2ZmbGluZV9hY2Nlc3MgcHJvZmlsZSBlbWFpbCIsInNpZCI6ImNmYWI4OTlkLTdhNDEtNGE5OS1hNTc1LWU1ZDViZmQ0YjVlYiIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiYWRkcmVzcyI6e30sInByZWZlcnJlZF91c2VybmFtZSI6ImRlbW8ifQ.kKXsuRxADD2Nsqf-0cbMCUVE8iOAo5HGLHPS8L1eLmlgYvcTN4EIl7Htm13w_quWlwDBFcb6o_WnyRYP5F2xXdGweep_96vHHPXNfF3wm9xsRVQLzIA9iZrNjKkX0Gq7ptZiiBWl1TnJS1LfXZaB9sYVIHDaKMiL4MrFuLloo_K7fNc_F4CYHEtHmt9x-bQjEPg4I2OPsyo0jvILIQfRSooX3Q8_jlJ_STrHxFA7Q0yVej2LkhSlfQBtDNor11R-b4mjjn6SjIH2qRQVTam5CMR_b7Pi3tO9yrL7QRfHBt2Me5tME8hPN0yN35YkbIVIhf6M2a3drvBqyvQcAsmfCA","type":"text"}],"body":{"mode":"raw","raw":""},"url":"{{endpoint}}/gateways"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 22 Nov 2023 14:42:34 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"Apache/2.4.57 () OpenSSL/1.0.2k-fips"},{"key":"Cache-Control","value":"max-age=0, must-revalidate, private"},{"key":"Allow","value":"GET"},{"key":"X-Robots-Tag","value":"noindex"},{"key":"Expires","value":"Wed, 22 Nov 2023 14:42:34 GMT"},{"key":"Vary","value":"Authorization"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": 11,\n \"reference\": \"14f4597d-ef96-4263-8107-1e1970959133\",\n \"libelle\": \"SandboxSemoa\",\n \"psp\": {\n \"libelle\": \"SANDBOX\",\n \"logo_url\": \"https://cashpay.s3.eu-west-1.amazonaws.com/psp/SandBox.png\"\n },\n \"methode\": \"DIRECT_URL\",\n \"logo_url\": null\n },\n {\n \"id\": 1,\n \"reference\": \"016eb63c-f29d-4384-92e4-b1bd37ef69f8\",\n \"libelle\": \"FloozTG-Ecom-Semoa\",\n \"psp\": {\n \"libelle\": \"FLOOZ\",\n \"logo_url\": \"https://cashpay.s3.eu-west-1.amazonaws.com/psp/Flooz.png\"\n },\n \"methode\": \"PUSH_USSD\",\n \"logo_url\": null\n },\n {\n \"id\": 2,\n \"reference\": \"a2c87957-1033-46e9-8706-056e45737de1\",\n \"libelle\": \"TmoneyGateway1\",\n \"psp\": {\n \"libelle\": \"T_MONEY\",\n \"logo_url\": \"https://cashpay.s3.eu-west-1.amazonaws.com/psp/Tmoney.png\"\n },\n \"methode\": \"USSD\",\n \"logo_url\": null\n },\n {\n \"id\": 6,\n \"reference\": \"52bfd484-13ef-44f3-b128-adf7187779b0\",\n \"libelle\": \"Ecobank-Mobile-Gtw\",\n \"psp\": {\n \"libelle\": \"Ecobank-Mobile\",\n \"logo_url\": \"https://cashpay.s3.eu-west-1.amazonaws.com/psp/ecobank_mobile.png\"\n },\n \"methode\": null,\n \"logo_url\": null\n },\n {\n \"id\": 14,\n \"reference\": \"f7bbfaef-eba3-4b82-ac31-61eb2b772289\",\n \"libelle\": \"Semoa-Orabank-NGO\",\n \"psp\": {\n \"libelle\": \"ORABANK-NGO\",\n \"logo_url\": \"https://cashpay.s3.eu-west-1.amazonaws.com/psp/mastercard.png\"\n },\n \"methode\": \"DIRECT_URL\",\n \"logo_url\": null\n }\n]"}],"_postman_id":"5ef875c0-6cf3-40de-8fe4-a916d4a8261a"}],"id":"d8baa0d5-8d8f-401c-997d-9a1787a7ef60","_postman_id":"d8baa0d5-8d8f-401c-997d-9a1787a7ef60","description":""},{"name":"Orders","item":[{"name":"Order list","event":[{"listen":"prerequest","script":{"id":"25ff702a-0203-4881-b9e6-a52be7c95912","exec":["function getApiSecure()","{"," var login = environment.login;"," var apiKey = environment.api_key;"," var salt = Date.now();"," var some = login + apiKey + salt;"," var apiSecure = CryptoJS.SHA256(some).toString();"," var result = {};"," result.api_secure = apiSecure;"," result.salt = salt;"," return result;","}","","var data = getApiSecure();","","postman.setEnvironmentVariable('api_secure', data.api_secure);","postman.setEnvironmentVariable('salt', data.salt);"],"type":"text/javascript","packages":{}}},{"listen":"test","script":{"id":"4057c290-d228-4dc1-8db1-c89b6a94c822","exec":["pm.test(\"response is ok\", function(){"," pm.response.to.have.status(200);","});",""],"type":"text/javascript","packages":{}}}],"id":"c7410c1b-604e-4953-8eb0-77f3f37e23da","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This resource is used to get the list of invoices.
\nyou can add some parameters in the query like terminal id to filter orders by a terminal.
\nResponse :
\nThis resource is used to Link2Pay integration.
\nThe Link2Pay service enables merchants to accept payments through a unique, shareable link. This link can be distributed via various channels such as email, SMS, or social media. Upon clicking the link, customers are directed to a secure payment page where they can complete their transaction.
\nLink Creation: Merchants generate a unique payment link (bill_url) through the platform.
\nLink Distribution: The generated link (bill8url) is shared with customers via preferred communication channels.
\nCustomer Payment: Customers click on the link, which directs them to a secure payment page wich displays differents method of payments.
\nPayment Completion: Customers choose their payment method and complete the transaction.
\nConfirmation: Merchants receive a notification confirming the payment.
\nThis resource is used to POS integration
\nPOS mode refers to a payment method where transactions are completed in person at a physical location using a Point of Sale terminal or device. Instead of online links, customers interact directly with a merchant’s POS device to make payments.
\nTransaction Initiation:
\nThe merchant enters the transaction amount into the POS terminal or connected device.
\nCustomer Payment:
\nThe customer pays using one of the supported payment methods:
\nDebit or credit card (swipe, chip, or contactless/NFC)
\nMobile money or mobile wallet
\nQR code scan (for linked payment apps)
\nAuthorization:
\nThe POS device communicates with the payment processor directly to authorize the payment in real time.
\nConfirmation:
\nOnce approved, the POS prints or displays a receipt, and the transaction is recorded in the merchant’s account.
\nAllow to check the status of a bill with it’s short code.
If the bill was already paid, the short
code will be deactivated and bill not available through this resource. In this case, you can use order reference or merchant order reference
Parameters:
\nResponse :
\nThis resource is used to create a ledger for a terminal
\nThis resource is used to get the details of a ledger.
\nThis resource is used to get the list of ledger of a specific terminal.
\nThis resource is used to closed a ledger
\nExample of callback:\nIn this example, apikey = ohPQj2Wi4XbjGBBSJVklnCp5qRr1XBBXE3vb\nWhen you decode the following token with this apikey, you should obtain the following result
\n{\n \"order_reference\": \"1635260290-9IV7ZA\",\n \"amount\": 40000,\n \"state\": \"Paid\",\n \"date_create\": \"2021-10-26T14:58:10+00:00\",\n \"bill_url\": \"https://dev.semoa-payments.ovh/facture/1635260290-9IV7ZA\",\n \"merchant_reference\": \"1692388802\",\n \"client\": {\n \"phone\": \"+22891941381\"\n },\n \"received_amount\": 40000,\n \"payments\": [\n {\n \"amount\": 40000,\n \"thirdparty_reference\": \"2001478375307284\",\n \"payment_date\": \"2021-10-26T15:02:25+00:00\",\n \"gateway\": {\n \"libelle\": \"Semoa-Orabank\"\n }\n }\n ]\n}
\n","urlObject":{"protocol":"https","host":["your","callbackURL","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"77149b8b-1857-4817-b874-e71078d9103e"}],"id":"dcc361af-e749-4caa-9efb-3638b2df5b5a","description":"Cashpay will notify your site by calling Callback url (POST) when a payment is validated, declined or cancelled. It is a called up from server to server. This means that the order form can be automatically validated even if the customer switches off or decides not to return to the eCommerce website, as this call does not pass through the browser.
\nThere are two differents methods to configure this url:
\n. The url is configured on Cashpay merchant parameters
\n. You provide the url when creating the bill (Section Create an order)
\nData are sent as JWT (Json Web Token). The token is signed using a secret key. You must decode this token to get data
\nPHP example:
\ntoken = JWT::encode(data, secretKey, algorithm='HS256')
\ndata = JWT::decode(token, secretKey, algorithm='HS256')
\nsecretKey is merchant's apikey
\nNB: When you implement your callback Url, note that you need to decode data with your apikey to get bill information.
\n","_postman_id":"dcc361af-e749-4caa-9efb-3638b2df5b5a"},{"name":"Contacts","item":[{"name":"add contacts","event":[{"listen":"prerequest","script":{"id":"990979cc-a8f3-4b6e-a9eb-84eabab050bf","exec":["function getApiSecure()","{"," var login = environment.login;"," var apiKey = environment.api_key;"," var salt = Date.now();"," var some = login + apiKey + salt;"," var apiSecure = CryptoJS.SHA256(some).toString();"," var result = {};"," result.api_secure = apiSecure;"," result.salt = salt;"," return result;","}","","var data = getApiSecure();","","postman.setEnvironmentVariable('api_secure', data.api_secure);","postman.setEnvironmentVariable('salt', data.salt);"],"type":"text/javascript"}},{"listen":"test","script":{"id":"9806a45d-febe-422a-9bb2-56e86adce4af","exec":["pm.test(\"response is ok\", function(){"," pm.response.to.have.status(201);","});",""],"type":"text/javascript"}}],"id":"65647495-0c76-469e-bc2a-cd40b4ff0f9d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"login","value":"{{login}}"},{"key":"apisecure","value":"{{api_secure}}"},{"key":"apireference","value":"{{api_reference}}"},{"key":"salt","value":"{{salt}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\t\n\t\"contacts\":[\n {\"phone\": \"+22898486419\",\n \"firstname\": \"UNKNOWN\",\n \"lastname\": \"UNKNOWN\",\n \"email\": \"unknown@gmail.com\"\n },\n {\n \"phone\": \"+22890833218\",\n \"firstname\": \"UNKNOWN\",\n \"lastname\": \"UNKNOWN\"\n }\n ],\n \"client_phone\": \"+22890112783\"\n}"},"url":"{{endpoint}}/contacts","description":"This resource is used to add contacts to a client.
\nParameters:
\nResponse :
\n