10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

By continuing your visit to this site without changing the settings of your cookies, you accept the use of
cookies allowing us to make business statistics

Read more (/cookies)

I agree

N\'diaye Waly Kevin

Orange Money WebPay Dev 

Enable your customer to pay for your products through Orange Money. Development API

1.0

[Link] 1/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

Use this API (/myapps/new/addapi/om-webpay-dev)

API reference (/apis/om-webpay-dev/api-reference) 

The Orange Money Web Payment API DEV (Sandbox) allows web merchants to integrate Orange Money as
means of payment in their website. Orange Money is a mobile payment solution across 17 countries in Africa
and the Middle East.

The Web Payment Sandbox is a E2E platform created for partners’ integration and testing.
Orange Money tests accounts (Merchant and Subscribers) are available to perform payment
transactions.
Integration Tools: USSD simulator and OM Payment Add-on (page)

Steps of test:
1. subscription via Orange Partner portal
2. access_token generation
3. Web Payment API
4. Transactions Status API

Watch the video below and see how you can use our API to offer Orange Money payment solution on your e-
commerce website.

video ([Link]

1- Web Payment Offer subscription - Getting My Merchant Key

You have been invited to subscribe the Orange Money Web Payment API. You are about to use your merchant
wallet in a secure way to offer a new payment method to your customers.

1.1 Application creation

[Link] ([Link]


[Link] 2/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer


[Link] 3/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

1.2 'Orange Money WebPayDev' API addition

You should have received an email with Channel User and subscriber identifiers:

Channel User:

id/login/name: MerchantWP00100
Merchant Account Number: 7701900100
Merchant Code: 101021
PIN code: xxxx

Subscriber:

MSISDN: 7701100100
PIN: xxxx

If it is not the case, please ask it by email to:

[Link]@[Link] ([Link]

So, add the API Orange Money Web Pay Dev to your Application and let's generate your Merchant Key by
entering your Merchant Account Number (channel user MSISDN) and Merchant Code

[Link] 4/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

Warning: Orange Money WebPay offers are hidden. You must have been invited to see them. The Merchant
Key will be created in the system only if you provide a valid Orange Money account and if you have proper
rights to subscribe the service. If you do not know your Merchant Code , please contact your local Orange
Money support team.


[Link] 5/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

IMPORTANT: The Merchant key will be used as Orange Money account identifier
for all payments transactions (no MSISDN, nor PIN will not be required in the API).
Please write down your Merchant Key and store it in a safe place.

Note that a single application can be subscribed to a DEV offer and a single country. For a second country,
you need to create a new application.
2. Get your Access token
Orange Money Web Payment API requires an Access token , based on your developer credentials (client id
and client secret).

[Link] 6/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

You can obtain your token with a simple call:

curl -X POST -H "Authorization: Basic {consumer_key}" \

-d "grant_type=client_credentials" \
[Link]

HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"access_token": "WI9VmGXfNB38s1e6A26Hob19AP2c",
"expires_in": "7776000"
}

Consumer_key is in Authorization header, by clicking on “Show” button:

So, in the example:

curl -X POST -H "Authorization: Basic YWtDc0dqbFhMRXI2dm1yd2pnUVhjdk53ZExiamdPdVQ6Y3d

HcjNENFdZQ1BYT0V0UA==" \
-d "grant_type=client_credentials" \
[Link]


[Link] 7/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"access_token": "IW3gdUVOvQVcO7mGNsOZgwdhDNvE",
"expires_in": "7776000"
}

Warning: Check you are using the right URL: /orange-money-webpay/dev/v1/webpayment HTTP/1.1

NOTE: The access_token is valid for the duration, in seconds, specified by expires_in. Therefore, you do not
need to request a new access token as your client application doesn't receive an error indicating that your
access token expired. At the present time, access_token have a lifetime of about 90 days.

If your token is expired, you just have to get a new token by the same method.

You can get more details about token here ([Link]

3. Web Payment API

This API allows you to create a payment session in the Orange Money system. A payment transaction will be
created based on the information provided in your request and a Payment Token will be returned in the API
response.

3.1 Web Payment request

3.1.1 Web Payment transaction initialization

You have to send a post:

[Link]

Authorization: Bearer IW3gdUVOvQVcO7mGNsOZgwdhDNvE

Accept: application/json
Content-Type: application/json
{
"merchant_key": "a86b2087",
"currency": "OUV",
"order_id": "MY_ORDER_ID_08082105_0023457",
"amount": 1200,
"return_url": "[Link]
"cancel_url": "[Link]
"notif_url": "[Link]
"lang": "fr"
"reference": "ref Merchant"
}


[Link] 8/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

Content-Type: application/json

{
"status":201,
"message":"OK",
"pay_token":"f5720dd906203c62033ffe64ed75614785878b0ab2231d9c582b2908fca0ab9a",
"payment_url":"https:\/\/[Link]\/payment\/pay_token\/f
5720dd906203c62033ffe64ed75614785878b0ab2231d9c582b2908fca0ab9a",
"notif_token":"dd497bda3b250e536186fc0663f32f40"
}

Warning : On API DEV we use OUV as currency. On API country is the country currency.

Note that the field ''order_id'' must be unique for the system.

The fields order_id and reference are limited to 30 chars and return_url, cancel_url and notify_url to 120 chars

The field reference refers to the merchant name

You can find below an example of the code for a postman request:

POST /orange-money-webpay/dev/v1/webpayment HTTP/1.1

Host: [Link]
Content-Type: application/json
Authorization: Bearer R5EVAffaxgpTojhuTorBSU1qMHgy
Accept: application/json
Cache-Control: no-cache
Postman-Token: e18f3aac-9bd7-ddc5-a3a4-668e6089a0d5

{
"merchant_key": "ad8b9717",
"currency": "OUV",
"order_id": "TestOPE_001903",
"amount": 1500,
"return_url": "[Link]
"cancel_url": "[Link]
"notif_url": "[Link]
"lang": "fr",
"reference": "ref Merchant"
}

OK! Now, all that you need is to redirect your client to our secured payment page: [Link]
[Link]-
[Link]/payment/pay_token/a4b2a348ee580b0d21fd3b2b9d67e1aeca739a28ca6d60d99f1bc833b8ffb909
([Link]
[Link]/payment/pay_token/a4b2a348ee580b0d21fd3b2b9d67e1aeca739a28ca6d60d99f1bc833b8ffb909)


[Link] 9/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

In order to ask for an OTP code and confirm your transaction, you can use the Sandbox Simulator.

Once the transaction is confirmed by the Orange client, the system will redirect the user to your return_url .
Then, a HTTP notification will be posted to the notif_url you sent in the web payment request.

3.1.2 Web Payment request URLs

There is 3 urls in the webpayment request:

return_url: the url of the web site where the customer will return when the payment will be finished and
the customer decide to click on the return link of the web payment web site
cancel_url: the url of the web site where the customer will return when the payment will be canceled by
the customer by clicking on the cancel link of the web payment web site
notif_url: the notification url used by the webpayment backend to notify the merchant backend of the
status of the payment’s transaction (see more details at “Transaction Notification”). This notification is
only sent when the payment process is confirmed and when it ends with a ‘SUCCESS’ or ‘FAILED’ status

These urls are sent in the body of the webpayment request, so the merchant can use dynamics urls that
depends on the merchant web site context (e.g. with url parameters like “&returnOnCart=1”,
“&referrer=[Link]”).

One WebPayment account can be used to centralize the merchant money of multiple web sites by putting the
same credentials/merchant_key in the requests sent to the WebPayment backend. Because the webpayment
request urls parameters are dynamically set during the build of the body of the request, each web site can use
its own URLs.

Example:

[Link]

POST [Link]
([Link] –
Bearer IW3gdUVOvQVcO7mGNsOZgwdhDNvE
"merchant_key": "a86b2087"
“return_url”: “[Link]/webpayment_returnurl_1”
“cancel_url” : “[Link]/webpayment_cancelurl_1”
“notif_url” : “[Link]/webpayment_notifurl_1”

[Link] 
[Link] 10/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

POST [Link]
([Link] –
Bearer IW3gdUVOvQVcO7mGNsOZgwdhDNvE
"merchant_key": "a86b2087"
“return_url”: “[Link]/webpayment_returnurl_2”
“cancel_url” : “[Link]/webpayment_cancelurl_2”
“notif_url” : “[Link]/webpayment_notifurl_2”

3.2 OTP code getting (via Partner USSD Sandbox Simulator)

The Partner Sandbox simulator is a Web based interface allowing partners and developers to perform the
following transactions in the Sandbox environment:

OTP request
Merchant Balance request
Subscriber Balance request

You can access the Simulator: [Link]

([Link]

You can login with the merchant account provided for the Sandbox (login: Merchant Account Number,
password: channel user Id).

Then you can request for an OTP with the subscriber PIN code.

You just have to fill the OTP code in the payment page, and click on “Confirmer”: 
[Link] 11/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

Once MSISDN and OTP are filled in the payment page, click on “Confirmer”:

… and the HTTP notification is posted to the notif_url you sent in the web payment request.

Warning: make sure you have implemented the notif_url to have visibility on payment status, if not you will not
be able to validate in real time the order and change its status on your database

3.3 Transaction Notification

The client has confirmed the transaction! Orange Money has just sent the Payment Notification to your
notif_url

[Link] 12/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

POST [Link]
{
"status":"SUCCESS",
"notif_token":"dd497bda3b250e536186fc0663f32f40",
"txnid": "MP150709.1341.A00073"
}

Warning: Do you remember the notif_token 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.

4. Transactions Status API

In addition of Transaction Notification, you can use the Transaction Status API 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)

[Link]
Accept: application/json
Authorization: Bearer WI9VmGXfNB38s1e6A26Hob19AP2c
Content-Type: application/json
{
"order_id": "MY_ORDER_ID_08082105_0023457",
"amount": 1200,
"pay_token": "f5720dd906203c62033ffe64ed75614785878b0ab2231d9c582b2908fca0ab9a"
}

201 Created
Content-Type: application/json; charset=utf-8

{
"status": "SUCCESS",
"order_id": "MY_ORDER_ID_08082105_0023457",
"txnid": "MP150709.1341.A00073"
}

The status could take one of the following values: INITIATED; PENDING; EXPIRED;
SUCCESS; FAILED

INITIATED waiting for user entry

PENDING user has clicked on “Confirmer”, transaction is in progress on Orange side
EXPIRED user has clicked on “Confirmer” too late (after token’s validity)
SUCCESS payment is done
FAILED payment has failed

If the transaction is not tried (the customer doesn’t do anything, or returns on Merchant site), status stays on
INITIATED state. By default, the the token’s validity is 10 minutes. The passage from PENDING state to
SUCCESS or FAILED state is rapid.

5. API reference
You can find the API description with more details and error codes on the API reference.

6. Troubleshooting 
[Link] 13/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

Error
message Description Solution Contact

Simulator – The Verify the test Channel User [Link]@[Link]

Authentication developer is credentials are right. Login : ([Link]
error not able to MSISDN Merchant (ex:
log to the 7701900008) Pwd : id/login
simulator merchant (ex:
MerchantWP00008)

Web Payment The partner Verify Notification URL of the [Link]@[Link]

- Notification has not partner ([Link]
is not received the
received notification

Subscription Something test this by creating a [Link]

to an went wrong '''new''' application us
application - in the ([Link]
Wrong exchange us)
parameter between
OPE and
Orange
Money
back end.

Subscription The Orange Money WebPay Country Admin or Georgiana Cruceru

to an developer offers are hidden. ([Link]@[Link]
application – cannot add developers must be invited ([Link]
Not seeing an the Web to see them
offer Pay API

Subscription When the error appears at [Link]@[Link]

to an first subscription please ([Link]
application - verify “Merchant Account
An error as Number”. When the error
occurred, appears at subscription after
please try the developer deleted
again later subscription. Developer
must create a new
application and subscribe it
again to the right Orange
Money WebPay offer. A
single application can be
subscribed to a DEV offer
and a single country. For a
second country, the
developer needs to create a
new application.


[Link] 14/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

Error
message Description Solution Contact

Using API – Wrong check the URL that the [Link]@[Link]

Unauthorized country developer is requesting ([Link]
to access the against the one(s) the
API application is subscribed for.
It might be wrong otherwise
check with a legit token
/orange-money-
webpay/dev/v1/webpayment
HTTP/1.1

Using API – The field ''order_id'' must be [Link]@[Link]

Order already unique for the system. This ([Link]
exists one has already been used
somewhere else "order_id":
"TestOPE_001503"

Using API – a single the correct one can be found [Link]@[Link]

Unauthorized currency is in the related documentation ([Link]
currency allowed per WebPay DEV : OUV WebPay
API offer country : as per OMC Core
platform

Using the API: Returned The issue lies with the value [Link]@[Link]
Transaction Status : of the parameters (amount, ([Link]
status NOT order_id and application_id);
resource FOUND all 3 must be correct
simultaneously. The
developer may want to
double check them. against
their logs.

Using the API: verify that you are well filled [Link]@[Link]
Payment the OTP code in order to ([Link]
failed validate the payment
transaction, with the correct
MSISDN (client number)

7. List of common error codes

http API
code code Message Description Comments

403 50 forbidden access denied by 'Unauthorized Access Layer' or 'Unauthorized

access to the ACL applicationId' or ‘Unauthorized country’
api

403 1201 forbidden forbidden transaction you are not allowed to do this action
access to the
api


[Link] 15/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

http API
code code Message Description Comments

403 1202 forbidden invalid merchant key your merchant key is wrong. you need to check it
access to the
api

403 1203 forbidden Unauthorized Check the currency you put in your request
access to the currency for this
api country

403 1204 forbidden Order Already exists The order_id must be unique in the system. Only
access to the one Token per order_id
api

Find us on

 ([Link]  ([Link]

 ([Link]

 ([Link]

 ([Link]

Co-innovate
([Link]
Identity & authentication (/identity-and-authentication/)
IoT & data analytics (/iot-and-data-analytics/)
Monetization & payment (/monetization-and-payment/)

Products
([Link]
Europe (/europe-catalogue/)
Middle East & Africa (/products-middle-east-and-africa/)

Blog
(/blog)
Events (/blog/?type=events)
News (/blog/?type=post)
Orange explains (/blog/?type=orange_explains)
Technical guides (/support/technical-guides/)
Testimonials (/blog/?type=testimonials)
Use cases & webinars (/blog/?type=use_cases_webinars)

Stay in touch Subscribe to newsletter  Contact us (/support/contact-us)


[Link] 16/17
10/08/2019 Orange Money WebPay Dev – Getting started – Orange Developer

© Orange 2019

About us ([Link]

Cookies ([Link]

Legal information ([Link]

Orange APIs General Terms (/orange-apis-general-terms)

Friendly links ([Link]


[Link] 17/17