Welcome to the documentation of the Paymetrust API. This documentation describes the different operations you can perform with our API. This section presents the basics to get started with the Paymetrust API, including prerequisites and available environments.
\nTo access and use the Paymetrust API, please follow the steps below:
\nGo to the official Paymetrust website at the following address: https://paymetrust.net/. Fill out the registration form with the required information.
\nAfter submitting the registration form, your request will be reviewed by the Paymetrust team. Once your registration is validated, an account will be created for you.
\nThe information to access your account, including your api_key and your api_password, will be sent to the email address you provided during registration. This information is essential to authenticate your requests to the Paymetrust API.
With your api_key and your api_password, you will be able to consume the Paymetrust API by following the provided documentation. Make sure to keep your authentication information secure and only share it with authorized parties.
The Paymetrust API uses token-based authentication. You must include a valid authentication token in each request.
\nSandbox: https://api.sandbox.paymetrust.net/v1/
Production: https://api.paymetrust.net/v1/
The request body must be in JSON format and include the following properties:
\n\n\nNote
\n
Note that the field merchant_transaction_id must be unique for the system.
The fields merchant_transaction_id and reference are limited to 30 chars and success_url, failed_url and notify_url to 120 chars
client_phone_number must be filled, if you don't want your customer to change his phone number when he confirms payment on payment gateway. Additionally, an option will be activating on your account to allow this.
You must redirect your customer to the payment_url in order to make payment
Your account is linked with only one currency, you must send the same currency as your account
\nAfter initiated the payment, you will obtain the payment_url. You must send your customer there so that they can pay
you have an account (account_key/account_password) in each country for which you want to process. We therefore use the token generated from your account_key to identify the country and then fix it on the checkout form.
\nit will allow you to proceed in the full payment process without redirecting users to our gateway page. For payment methods that support this type of process, users will stay in your application and finalize the whole process of payment (deposit) there.
\nThe following parameters need to be added in your payment initialization request for making a direct payment process :
\ndirect_pay (boolean true/false): should be always set to true, for taking advantage of the direct payment feature (payment without walking through our gateway)
\notp_code (For Orange only): A 4 or 6-digit code (depending on our country) that should be provided by end user. You need to prepare a field to let user enter this OTP code in, and send it back in the request to our API.
\nclient_phone_number must also be filled when you use direct payment mode (e.g : +2250707000000)
\n- NEW PARAMETERS THAT YOU RECEIVE IN THE RESPONSE
\nAfter sending the request with parameters specified above, you will receive a response from us containing the following:
\n{\n \"code\": 200,\n \"status\": \"OK\",\n \"payment_token\": \"1ee9f52a2704628c81590242d1c176b51240d7b5fd7e4bae9\",\n \"notify_token\": \"0554967cbd9c439198827cb5dfd845f1\",\n \"transaction_id\": \"4dc38466f77a4114a82bfc0d7a618213\",\n \"merchant_transaction_id\": \"TEST_SN_PO0190\",\n \"payment_url\":\n \"https://secure.sandbox.paymetrust.net/payment/1ee9f52a2704628c81590242d1c176b51240\nd7b5fd7e4bae9\",\n \"details\": {\n \"code\": 2010,\n \"status\": \"FAILED\",\n \"message\": \"Paiement échoué\",\n \"must_be_redirected\": false\n }\n}\n\nThe only new parameter that has been added in this response is details. It is an object that holds all the information regarding your direct payment status. Inside it, you can find the following parameters:
\ncode: A numeric status code that specifies the status of the payment.
\nstatus: A string value that also specifies the status of the payment. You should rely on this status to process the payment in your side. Its values can be either:
- SUCCESS: That means the user was successfully debited, and the payment was successful.
- FAILED: That means the user did NOT complete the payment, or encountered error in operator’s level.
- INITIATED: That means the payment is being processed by the user
- PENDING: That means the payment is still being processed by the user
message: This text must be shown to the user
\nOnce payment is successful initialized you must check value of field must_be_redirected in the response and then redirect user to payment_url if the value of field is set to true.
\n","urlObject":{"path":["v1","payment"],"host":["https://api.sandbox.paymetrust.net"],"query":[],"variable":[]}},"response":[{"id":"3aab6ff5-b6d4-4409-b6ec-acf4b057295d","name":"SUCCESS","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"currency\": \"XOF\",\n \"payment_method\": \"OM\",\n \"merchant_transaction_id\": \"MY-ORDER-ID-08082106\",\n \"amount\": 100,\n \"success_url\": \"https://8cbbcb8d08d6.ngrok.io\",\n \"failed_url\": \"https://8cbbcb8d08d6.ngrok.io/cancel/\",\n \"notify_url\": \"https://8cbbcb8d08d6.ngrok.io/notification\",\n \"lang\": \"fr\",\n \"designation\": \"Donation for REZ NGO\",\n \"client_first_name\" : \"John\",\n \"client_last_name\" : \"Doe\",\n \"client_phone_number\" : \"+2250707000000\",\n \"client_email\" : \"john.doe@gmail.com\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.paymetrust.net/v1/payment"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Date","value":"Wed, 16 Sep 2020 15:39:29 GMT"},{"key":"Date","value":"Wed, 16 Sep 2020 15:39:29 GMT"},{"key":"Connection","value":"close"},{"key":"X-Xdebug-Profile-Filename","value":"/var/tmp/cachegrind.out.61285"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Content-Type","value":"application/json"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"phpdebugbar-id","value":"X77443d03e351405ec8fb6654f4e60dc0"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"\n{\n \"code\": 200,\n \"status\": \"OK\",\n \"payment_token\": \"1ef969cf5da467dc98c70242f6c351d52eb3ff889b0f4f9e94078a1a0da6a2a3\",\n \"notify_token\": \"382a2329ae0647f896fa70283fa087cc\",\n \"transaction_id\": \"4c9a7225819943fe9f1eab6ef5b573a5\",\n \"merchant_transaction_id\": \"k0oqli6ns26xyrf\",\n \"payment_url\": \"BASEPAYURL/payment/1ef969cf5da467dc98c70242f6c351d52eb3ff889b0f4f9e94078a1a0da6a2a3\",\n \"details\": {\n \"code\": 2001,\n \"status\": \"INITIATED\",\n \"message\": \"Veuillez cliquer sur le lien pour continuer le paiement\",\n \"must_be_redirected\": true\n }\n}"},{"id":"c8fb222f-cee2-4100-b10d-5bfbd421f062","name":"ERROR","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"currency\": \"XOF\",\n \"merchant_transaction_id\": \"MY-ORDER-ID-08082106\",\n \"amount\": 1200,\n \"success_url\": \"https://8cbbcb8d08d6.ngrok.io\",\n \"failed_url\": \"https://8cbbcb8d08d6.ngrok.io/cancel/\",\n \"notify_url\": \"https://8cbbcb8d08d6.ngrok.io/notification\",\n \"lang\": \"fr\",\n \"designation\": \"Donation for REZ NGO\",\n \"client_first_name\" : \"John\",\n \"client_last_name\" : \"Doe\",\n \"client_phone_number\" : \"+2250707000000\",\n \"client_email\" : \"john.doe@gmail.com\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.paymetrust.net/v1/payment"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Host","value":"127.0.0.1:8000"},{"key":"Date","value":"Wed, 16 Sep 2020 15:38:07 GMT"},{"key":"Date","value":"Wed, 16 Sep 2020 15:38:06 GMT"},{"key":"Connection","value":"close"},{"key":"X-Xdebug-Profile-Filename","value":"/var/tmp/cachegrind.out.61285"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Content-Type","value":"application/json"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"phpdebugbar-id","value":"Xca434cdc0466e1ef51be8cf5a1f1a662"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1200,\n \"status\": \"TRANSACTION_EXIST\",\n \"description\": \"La transaction existe déjà\"\n}"}],"_postman_id":"89a43c20-ec90-4736-b967-9702dab04960"},{"name":"Payment Status","id":"7fa2df84-1319-42cb-b42b-59d01380577a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"YOUR-BEARER-AUTH"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.sandbox.paymetrust.net/v1/payment/{payment_token}","description":"In addition, of Transaction Notification, you can use the Transaction Status that allows you to consult in real time the current status of a payment. In practice, this can be useful for cases where notification are not sent (e.g. when users don’t validate their payments)
\nYou put the payment_token on the URL or the transaction_id returned after initialization.
You can also use merchant_transaction_id parameter, which is your transaction ID on your side.
The Web Payment API, also known as \"Payment\", allows the creation of payment sessions in the PaymeTrust system. Using this API, you can initiate a payment transaction by providing the necessary information in your request, and a payment token will be generated and returned in the API response.
\nPOST: v1/payment
The request body must be in JSON format and include the following properties:
\nIn addition to transaction notification, you can use transaction status to check the current status of a payment in real-time. In practice, this can be useful in cases where notifications are not sent (e.g., when users do not validate their payments).
\n","urlObject":{"path":["v1","transfer","{transaction_id}"],"host":["https://api.sandbox.paymetrust.net"],"query":[],"variable":[]}},"response":[{"id":"e257fd95-aa44-4d81-af79-becfb070b901","name":"SUCCESS","originalRequest":{"method":"GET","header":[],"url":"https://api.sandbox.paymetrust.net/v1/transfer/69c9c46c18384f89852924ab88686058"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.19.2"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Xdebug-Profile-Filename","value":"/var/tmp/cachegrind.out.29389"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Tue, 22 Sep 2020 07:55:26 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"phpdebugbar-id","value":"Xcf24c4b323510983d705e909f7d2b50d"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 100,\n \"status\": \"SUCCESS\",\n \"merchant_transaction_id\": \"MY-ORDER-ID-0808100\",\n \"transaction_id\": \"3794955185b04d32956cfb65cd8b744f\",\n \"amount\": \"100\",\n \"fee_amount\": \"2\",\n \"user\": {\n \"name\": \"Account Test\",\n \"email\": \"customer@pmt.com\",\n \"phone_number\": \"+2250101002201\"\n }\n}"},{"id":"0f81ed1a-1539-48be-becb-9595f86b9cd1","name":"ERROR","originalRequest":{"method":"GET","header":[],"url":"https://api.sandbox.paymetrust.net/v1/transfer/NOT_EXIST_TRANSACTION_ID"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.19.2"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-Xdebug-Profile-Filename","value":"/var/tmp/cachegrind.out.78196"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Tue, 22 Sep 2020 07:56:00 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"phpdebugbar-id","value":"Xf49025f60563c2cb603c6436c569e8c3"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 404,\n \"status\": \"NOT_FOUND\",\n \"description\": \"Not found\"\n}"}],"_postman_id":"e5998cf8-501a-45c0-8fc9-0c230e51c84e"}],"id":"34a77255-638d-4cc6-a94c-681e03eb1293","description":"The Transfer API, commonly referred to as \"Transfer\", is an essential component that enables secure and efficient data transmission between the Paymetrust system and various platforms. This API is designed to provide robust and flexible solutions for managing fast and secure money transfers.
\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"d3e9f923-97f0-4416-93e4-9e2532e2ad13"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"d555dc27-1d8b-418b-8beb-734a2dba03e0"}}],"_postman_id":"34a77255-638d-4cc6-a94c-681e03eb1293"},{"name":"Balance","item":[{"name":"Balance","id":"a9c25bb6-c0a1-4ac7-890a-cfc849539d05","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This is the official documentation to handle the merchant account balance API.
\nUsage: This API allows you to get the amount available on your merchant account on our side.
\navailable_balance represents your account available balance in Paymetrust system. This balance is the one used for transfers operations.
\n\n","_postman_id":"f84d0679-6091-4783-8d3f-d2df1baf74fb"},{"name":"Transaction Notification","item":[],"id":"4339d983-73f8-464b-8ded-73be23825d3d","description":"N.B: You need to be authenticated and send the valid access token received after logging in as a bearer token in the header of the request.
\n
Notification is a mechanism to implement in order to automatically synchronize payments to your merchant site. Paymetrust will call this link after each update to notify you of status changes during a transaction. At the end of a payment, Paymetrust systematically calls the notification URL for the service concerned. The purpose of this call is to inform the merchant of the status of their transaction. The merchant can then validate their order if the payment is verified and accepted.
\nWhen the transaction (payment or transfer) has a final status (SUCCESS or FAILED)! Paymetrust will send a payment notification to you notify_url with the following parameters:
notify_token: this is the same as the one present in the web payment response, make sure this token matches the token sent in the POST notification. This way, you will validate the authenticity of the notification.
merchant_transaction_id: represents the unique identifier of your order sent in the request
transaction_id: represents the unique identifier of the order for this operation.
The request body is in JSON format as follows:
\nWhen you make a payment request using the Paymetrust API, you must provide three important URLs for handling notifications and redirections after payment. Here is a detailed explanation of each URL:
\n\"success_url\" : \"https://8cbbcb8d08d6.ngrok.io\"\n\n\n\nThis URL is used to redirect the user after a successful payment. Once the payment is completed successfully, the user will be automatically redirected to this URL. Make sure this page provides visual confirmation and transaction details to the user.
\n
\"failed_url\" : \"https://8cbbcb8d08d6.ngrok.io/cancel/\"\n\n\n\nhis URL is used to redirect the user in case of payment failure or cancellation by the user. If the payment cannot be completed for any reason, the user will be redirected to this URL. This page should inform the user of the transaction failure and provide options to retry the payment or contact support.
\n
\"notify_url\": \"https://8cbbcb8d08d6.ngrok.io/notification\"\n\n\n\nThis URL is used by the Paymetrust server to send notifications about the payment status. Once the payment is processed, Paymetrust will send a POST request to this URL containing the transaction details and its status. You must implement an endpoint at this URL to receive and process these notifications. Make sure your endpoint can handle requests securely and update the transaction status in your system.
\n
When the transaction (payment or withdrawal) has a final status (SUCCESS or FAILED) ! PaymeTrust will send the Payment Notification to your notify_url with following params :
\nnotify_token : this is the same present in the web payment response, Make sure this token matches the token sent in the notification POST. This way, you will validate the authenticity of the notification.
\nmerchant_transaction_id : represents your unique order ID sent in request
\ntransaction_id : represents our unique order ID for this operation.
\nIt's a JSON post request
\nbelow the format
\n{\n \"notify_token\": \"f92069a6b56c4bbd93ce1824ca005b8d\",\n \"merchant_transaction_id\": \"63e0fe766f390\",\n \"transaction_id\": \"50901a80c84b4edcb4f50ae864bfa7c5\",\n \"user\": {\n \"name\": \"Wadjo Mathias\",\n \"email\": \"orvilleberanger@gmail.com\",\n \"phone_number\": \"+2250767866856\"\n }\n}\n\nonce you have received the notification, you will check our system for the final status of the transaction.
\n","_postman_id":"4339d983-73f8-464b-8ded-73be23825d3d"},{"name":"Status codes","item":[],"id":"e6a26736-a8ff-464c-8a05-5bce725eac2a","description":"","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"5be6c483-a5d0-46c5-ac38-af1b6711be45"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"dbc10588-549a-4c23-bdf5-c5b367886701"}}],"_postman_id":"e6a26736-a8ff-464c-8a05-5bce725eac2a"},{"name":"Payment methods","item":[],"id":"b58ff6ec-fdee-4764-881b-efdb2b90a3b4","description":"","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"5be6c483-a5d0-46c5-ac38-af1b6711be45"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"dbc10588-549a-4c23-bdf5-c5b367886701"}}],"_postman_id":"b58ff6ec-fdee-4764-881b-efdb2b90a3b4"},{"name":"Operation Limits","item":[],"id":"4711fcbe-4bdc-4179-81c3-945ff4f436c0","description":"","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"5be6c483-a5d0-46c5-ac38-af1b6711be45"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"dbc10588-549a-4c23-bdf5-c5b367886701"}}],"_postman_id":"4711fcbe-4bdc-4179-81c3-945ff4f436c0"},{"name":"Best Practices","item":[],"id":"f131ca6a-48bf-4856-97a1-4d6c8d0ea9f9","description":"Authentication
\nUse environment variables to store your API keys securely.
\nImplement OAuth 2.0 for user authentication.
\nHandling Errors
\nUse try-catch blocks to handle exceptions.
\nLog errors and monitor them for quick resolution.
\nSecurity
\nUse HTTPS for all API requests.
\nRegularly review and update your API keys and tokens.
\nFor more details, refer to the PayMeTrust API Documentation.
\n","_postman_id":"f131ca6a-48bf-4856-97a1-4d6c8d0ea9f9"}],"event":[{"listen":"prerequest","script":{"id":"fac5acfa-6818-47dc-94ab-50f11e1a31da","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"90d750e1-1c35-4de5-9dd7-726aee452215","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://api.sandbox.paymetrust.net"},{"key":"bearerToken","value":"YOUR-BEARER-AUTH"},{"key":"merchantUrl","value":"https://mywebsite.com"},{"key":"account_key","value":"string"},{"key":"account_password","value":"string"}]}