### Usage Example
Source: https://docs.cinetpay.com/api/1.0-en/sdk/android
Example code snippet demonstrating how to initiate a payment by adding credentials.
```APIDOC
## Use of the package
To initiate a payment add your credentials in the: `app/src/main/java/com/cinetpay/androidsdk/sample/activities/MainActivity.java`
```java
String api_key = ""; // TODO A remplacer par votre clé API
String site_id = ""; // TODO A remplacer par votre Site ID
```
```
--------------------------------
### Installation
Source: https://docs.cinetpay.com/api/1.0-en/sdk/android
Instructions on how to add the CinetPay Android SDK to your project's dependencies.
```APIDOC
## Installation
Start the installation by cloning CinetPay Android SDK on Github
* Add `com.cinetpay:androidsdk` to your `build.gradle` dependencies
```java
dependencies {
implementation 'com.cinetpay:androidsdk:1.0.0'
}
```
```
--------------------------------
### Install CinetPay Python SDK
Source: https://docs.cinetpay.com/api/1.0-en/sdk/python
Installs the CinetPay SDK version 0.1.1 from the test PyPi repository using pip. Ensure pip is installed or install it using the provided curl command. For Windows users, consider enabling 'Long Paths' if installation fails due to path length limitations.
```bash
pip install -i https://test.pypi.org/simple/ cinetpay-sdk==0.1.1
```
```bash
$ curl https://bootstrap.pypa.io/get-pip.py | python
```
```bash
python setup.py install
```
--------------------------------
### Seamless SDK Integration Steps
Source: https://docs.cinetpay.com/api/1.0-en/sdk/js
This section details the steps required to integrate the CinetPay Seamless SDK into your web project, from importing the SDK to handling payment callbacks.
```APIDOC
## Importing the Seamless SDK
### Description
Link the seamless SDK to your page by including the script in the head tag.
### Method
HTML
### Endpoint
N/A
### Parameters
N/A
### Request Example
```html
```
### Response
N/A
```
```APIDOC
## Setup of Parameters
### Description
Configure the SDK with essential merchant and payment parameters to invoke the payment counter.
### Method
Javascript
### Endpoint
N/A
### Parameters
#### Request Body
- **apikey** (string) - Required - The identifier of the merchant.
- **site_id** (string) - Required - The service identifier.
- **mode** (string) - Required - 'PRODUCTION' or 'TEST'.
- **close_after_response** (boolean) - Optional - Closes the counter automatically (true or false).
- **type** (string) - Optional - 'WEB' or 'MOBILE' (Default is WEB).
- **notify_url** (string) - Required - Valid payment notification URL.
### Request Example
```javascript
CinetPay.setConfig({
apikey: 'YOUR_API_KEY',
site_id: YOUR_SITE_ID,
mode: 'PRODUCTION',
notify_url: 'https://mondomaine.com/notify/'
});
```
### Response
N/A
```
```APIDOC
## Sending Data for Checkout
### Description
Provide payment details to the SDK to load and display the payment counter to the buyer.
### Method
Javascript
### Endpoint
N/A
### Parameters
#### Request Body
- **transaction_id** (string) - Required - Unique identifier for the transaction.
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Required - The currency code (e.g., 'XOF').
- **channels** (string) - Optional - Payment channels to use (e.g., 'ALL').
- **description** (string) - Optional - Description of the payment.
- **metadata** (object) - Optional - Additional metadata.
### Request Example
```javascript
CinetPay.getCheckout({
transaction_id: 'YOUR_TRANSACTION_ID',
amount: 100,
currency: 'XOF',
channels: 'ALL',
description: 'YOUR_PAYMENT_DESCRIPTION'
});
```
### Response
N/A
```
```APIDOC
## Handling Payment Callbacks
### Description
Use the `CinetPay.waitResponse` method to observe the transaction status after payment and perform necessary actions.
### Method
Javascript
### Endpoint
N/A
### Parameters
#### Request Body
- **data** (object) - Contains the transaction details returned after payment.
- **amount** (string) - Amount paid.
- **currency** (string) - Currency.
- **status** (string) - Status of the transaction ('ACCEPTED' or 'REFUSED').
- **payment_method** (string) - Payment method used.
- **description** (string) - Description provided at initialization.
- **metadata** (string) - Metadata provided at initialization.
- **operator_id** (string) - Operator identifier.
- **payment_date** (string) - Payment date.
### Request Example
```javascript
CinetPay.waitResponse(function(data) {
// En cas d'échec
if (data.status == "REFUSED") {
if (alert("Votre paiement a échoué")) {
window.location.reload();
}
}
// En cas de succès
else if (data.status == "ACCEPTED") {
if (alert("Votre paiement a été effectué avec succès")) {
// correct, on delivre le service
window.location.reload();
}
}
});
```
### Response Example
```json
{
"amount": "100",
"currency": "XOF",
"status": "ACCEPTED",
"payment_method": "FLOOZ",
"description": "Description",
"metadata": "ABIDJAN",
"operator_id": "8211027064102",
"payment_date": "2021-10-27 09:47:09"
}
```
```
--------------------------------
### Example Invoice Data Structure
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
This snippet shows an example of the 'invoice_data' object structure, which can be used to include additional payment-related information such as remaining balance, invoice number, and academic year.
```json
"invoice_data":{
"Reste à payer":"25 000fr",
"Matricule":"24OPO25",
"Annee-scolaire":"2020-2021"
}
```
--------------------------------
### Initialization Parameters
Source: https://docs.cinetpay.com/api/1.0-en/sdk/android
Details on the mandatory parameters required to initialize the CinetPay counter.
```APIDOC
## Initialization of the counter
To function, the counter must receive data such as :
* **apikey** | The merchant ID | String | `Mandatory`
* **site_id** | The service identifier | Integer | `Obligatory`
* **notify_url** | Valid payment notification | URL | `Mandatory`
```
--------------------------------
### Example Phone Number Locking Configuration
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
This snippet illustrates how to configure phone number locking and provide a customer's phone number with a country code prefix for payment processing.
```json
"lock_phone_number": true,
"customer_phone_number" : "+2250504315545"
```
--------------------------------
### Initialize CinetPay SDK with Credentials
Source: https://docs.cinetpay.com/api/1.0-en/sdk/android
This code demonstrates how to initialize the CinetPay SDK by providing your API key and Site ID. These credentials are required to authenticate with the CinetPay payment gateway. Replace the placeholder values with your actual credentials.
```java
String api_key = ""; // TODO A remplacer par votre clé API
String site_id = ""; // TODO A remplacer par votre Site ID
```
--------------------------------
### Configure CinetPay SDK Parameters (Javascript)
Source: https://docs.cinetpay.com/api/1.0-en/sdk/js
This Javascript code configures the CinetPay SDK with essential merchant details. It requires the 'apikey', 'site_id', and 'notify_url'. The 'mode' can be set to 'PRODUCTION' or 'TEST'. This setup is crucial for identifying the merchant and handling payment notifications.
```javascript
CinetPay.setConfig({
apikey: 'YOUR_API_KEY',
site_id: YOUR_SITE_ID,
mode: 'PRODUCTION',
notify_url: 'https://mondomaine.com/notify/'
});
```
--------------------------------
### Response Handling
Source: https://docs.cinetpay.com/api/1.0-en/sdk/android
Information on how to manage and view responses (success or error) from CinetPay requests.
```APIDOC
## Management of responses
The different answers of the requests (success or error) are registered in the log : `app/src/main/java/com/cinetpay/androidsdk/sample/MyCinetPayWebAppInterface.java`
```java
@Override
@JavascriptInterface
public void onResponse(String response) {
Log.d("MyCinetPayWebApp", response);
}
@Override
@JavascriptInterface
public void onError(String response) {
Log.d("MyCinetPayWebApp", response);
}
```
```
--------------------------------
### Example Payment Response Data (JSON)
Source: https://docs.cinetpay.com/api/1.0-en/sdk/js
This JSON object represents the data structure returned by the CinetPay SDK after a payment attempt. It includes details such as the transaction amount, currency, status (ACCEPTED/REFUSED), payment method, description, and timestamps. This data is crucial for processing transactions on the merchant's side.
```json
{
"amount": "100",
"currency": "XOF",
"status": "ACCEPTED",
"payment_method": "FLOOZ",
"description": "Description",
"metadata": "ABIDJAN",
"operator_id": "8211027064102",
"payment_date": "2021-10-27 09:47:09"
}
```
--------------------------------
### Initialize CinetPay Client with API Credentials
Source: https://docs.cinetpay.com/api/1.0-en/sdk/python
Initializes the CinetPay client by passing API key and site ID directly to the constructor. Alternatively, the client can be initialized without parameters, in which case it will look for APIKEY and CLIENT_AUTH_TOKEN environment variables.
```python
from cinetpay_sdk.s_d_k import Cinetpay
apikey = "XXXXXXXXXXXXXXXXXX"
site_id = "XXXXXX"
client = Cinetpay(apikey,site_id)
```
--------------------------------
### iOS Info.plist Configuration for CinetPay
Source: https://docs.cinetpay.com/api/1.0-en/sdk/flutter
This snippet illustrates the required configuration within the iOS Info.plist file to allow arbitrary loads, which is necessary for the CinetPay SDK's network requests.
```xml
NSAppTransportSecurityNSAllowsArbitraryLoads
```
--------------------------------
### Flutter CinetPay Checkout Widget Usage
Source: https://docs.cinetpay.com/api/1.0-en/sdk/flutter
Demonstrates how to use the CinetPayCheckout widget in a Flutter application, including initialization parameters, payment data, and callback functions for response and error handling.
```dart
CinetPayCheckout(
title: 'Guichet de paiement',
configData: {
'apikey': 'YOUR_API_KEY',
'site_id': YOUR_SITE_ID,
'notify_url': 'https://mondomaine.com/notify/'
},
paymentData: {
'transaction_id': 'YOUR_TRANSACTION_ID',
'amount': 100,
'currency': 'XOF',
'channels': 'ALL',
'description': 'Test de paiement'
},
waitResponse: (response) {
print(response);
}
onError: (error) {
print(error);
}
);
```
--------------------------------
### Import Seamless SDK (HTML)
Source: https://docs.cinetpay.com/api/1.0-en/sdk/js
This snippet shows how to include the CinetPay Seamless SDK in the head section of an HTML page. It requires no external dependencies beyond a standard HTML structure and an internet connection to fetch the script from the CDN.
```html
```
--------------------------------
### Example Payment Request Payload
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
This JSON object represents a sample payload for initiating a payment request to the CinetPay API. It includes essential details such as amount, currency, transaction ID, return URLs, and customer information.
```json
{
"amount": 2500,
"currency": "XOF",
"apikey": "XXXXXXXXXXXXXXXX",
"site_id": "XXXXX",
"transaction_id": "REFID12354",
"description": "TRANSACTION DESCRIPTION",
"return_url": "https://www.exemple.com/return",
"notify_url": "https://www.exemple.com/notify",
"metadata": "user001",
"customer_id": "001",
"customer_name": "John",
"customer_surname": "Doe",
"channels": "MOBILE_MONEY"
}
```
--------------------------------
### Payment Data Parameters
Source: https://docs.cinetpay.com/api/1.0-en/sdk/android
Information about the data required to prepare and initiate a payment transaction.
```APIDOC
## Payment data
In order to make the payment, some data must be submitted to prepare the counter. Thus, we have :
* **amount** | Payment amount `(>= 100 XOF)` | Integer | `Obligatory`
* **currency** | Currency of payment (XOF - XAF - CND - GNF - USD) | String | `Obligatory`
* **Transaction_id** | The transaction identifier. It must be unique for each transaction| `Obligatory`.
* **description** | The description of your payment| `Obligatory`.
* **channels** | The payment universe. Can be: `ALL` - `MOBILE_MONEY` - `CREDIT_CARD` - `WALLET`. Default: `'ALL'` Any combination is applicable to comma separated: `'MOBILE_MONEY, WALLET'` | Character string | Optional
* **metadata** | String | Optional
* **customer_name** | Customer name `*` | Character string | Optional
* **customer_surname** | First name of the buyer `*` | String | Optional
* **customer_email** | Buyer's email address `*` | String | Optional
* **customer_phone_number** | Buyer's phone number `*` | String | Optional
* **customer_city** | Buyer's city `*` | Character string | Optional
* **customer_country** | Buyer's country. ISO2 country code (CI => Ivory Coast). Optional
* **customer_state** | String| Buyer's state (when USA is used as country) `*` | String | Optional
* **customer_zip_code** | Buyer's Zip Code `*` | Character string | Optional
> **Note** : `*` Mandatory if using the banking universe (CREDIT_CARD)
```
--------------------------------
### JavaScript Payment Integration with CinetPay SDK
Source: https://docs.cinetpay.com/api/1.0-en/sdk/js
This snippet shows how to configure and use the CinetPay SDK in JavaScript to initiate a payment. It sets API credentials, transaction details, and customer information, then handles payment responses and errors.
```html
SDK SEAMLESS
```
--------------------------------
### Android Permissions and Configuration for CinetPay
Source: https://docs.cinetpay.com/api/1.0-en/sdk/flutter
This snippet shows the necessary Android permissions and application configuration required for the CinetPay SDK to function correctly, including internet access and enabling cleartext traffic.
```xml
...
...
```
--------------------------------
### Initialize a Payment with CinetPay
Source: https://docs.cinetpay.com/api/1.0-en/sdk/python
Initializes a payment transaction using the CinetPay client. This requires providing transaction details such as amount, currency, transaction ID, description, return URL, and customer information. The function returns the result of the payment initialization.
```python
from cinetpay_sdk.s_d_k import Cinetpay
apikey = "XXXXXXXXXXXXXXXXXX"
site_id = "XXXXXX"
client = Cinetpay(apikey,site_id)
data = {
'amount' : 00000,
'currency' : "XOF",
'transaction_id' : "XXXXXXXXXXXXXXXX",
'description' : "TRANSACTION DESCRIPTION",
'return_url' : "https://www.exemple.com/return",
'notify_url' : "https://www.exemple.com/notify",
'customer_name' : "XXXXXXXXXXXX",
'customer_surname' : "XXXXXXXXXXXXX",
}
print(client.PaymentInitialization(data) )
```
--------------------------------
### Initialize and Process Payment with Javascript SDK Seamless
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
This snippet demonstrates how to initialize the CinetPay SDK Seamless in Javascript, configure payment parameters, and handle the response. It includes setting API keys, site ID, notification URL, transaction details, customer information, and payment channels. The function also includes logic to handle successful payments and refusals.
```html
SDK SEAMLESS
```
--------------------------------
### POST /v2/payment
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
Initiates a payment by generating a payment link. This endpoint accepts payment details and returns a URL for the customer to complete the transaction.
```APIDOC
## POST /v2/payment
### Description
Initiates a payment by generating a payment link. This endpoint accepts payment details and returns a URL for the customer to complete the transaction.
### Method
POST
### Endpoint
https://api-checkout.cinetpay.com/v2/payment
### Parameters
#### Request Body
- **apikey** (String) - Required - Your apikey provided by CinetPay.
- **site_id** (String) - Required - Your site_id provided by CinetPay.
- **transaction_id** (String) - Required - Unique transaction identification.
- **amount** (Integer) - Required - The amount of the transaction (must be a multiple of 5).
- **currency** (String) - Required - The currency (e.g., XOF, XAF, CDF, GNF, USD).
- **description** (String) - Required - Description of the current payment. Avoid special characters like #, /, $, _, &.
- **notify_url** (Url) - Required - The URL for payment notifications.
- **return_url** (Url) - Required - The URL to redirect the customer after payment.
- **channels** (String) - Required - Payment channels to enable (e.g., ALL, MOBILE_MONEY, CREDIT_CARD, WALLET). Defaults to ALL.
- **lang** (String) - Optional - The default language of the payment gateway (e.g., fr, en).
- **metadata** (String) - Optional - Any additional information for identifying or processing the payment (e.g., order reference).
- **invoice_data** (Object) - Optional - Additional information to display on the CinetPay invoice.
- **lock_phone_number** (Boolean) - Optional - If true, prefixes the phone number for payment validation. Used with `customer_phone_number`.
#### Credit Card Specific Parameters (Optional, when `channels` includes `CREDIT_CARD`)
- **customer_id** (String) - Optional - The customer's identifier in your system.
- **customer_name** (String) - Required - The customer's name.
- **customer_surname** (String) - Required - The customer's first name.
- **customer_phone_number** (String) - Required - The customer's phone number.
- **customer_email** (String) - Required - The customer's email address.
- **customer_address** (String) - Required - The customer's address.
- **customer_city** (String) - Required - The customer's city.
- **customer_country** (String) - Required - The customer's country ISO code (e.g., CI, TG, SN).
- **customer_state** (String) - Required - The customer's state.
- **customer_zip_code** (String) - Required - The customer's postal code.
### Request Example
```json
{
"apikey": "YOUR_API_KEY",
"site_id": "YOUR_SITE_ID",
"transaction_id": "TRANS12345",
"amount": 10000,
"currency": "XOF",
"description": "Payment for order #12345",
"notify_url": "https://yourdomain.com/notify",
"return_url": "https://yourdomain.com/return",
"channels": "CREDIT_CARD",
"customer_name": "John",
"customer_surname": "Doe",
"customer_phone_number": "+2250102030405",
"customer_email": "john.doe@example.com",
"customer_address": "123 Main St",
"customer_city": "Abidjan",
"customer_country": "CI",
"customer_state": "Abidjan",
"customer_zip_code": "01"
}
```
### Response
#### Success Response (200)
- **code** (String) - Status code of the operation.
- **message** (String) - Message describing the operation status.
- **payment_url** (String) - The URL generated for the payment.
#### Response Example
```json
{
"code": "00",
"message": "success operation",
"payment_url": "https://checkout.cinetpay.com/...?token=..."
}
```
```
--------------------------------
### Transaction Verification API
Source: https://docs.cinetpay.com/api/1.0-en/sdk/python
This API allows you to verify the status of a transaction using either its transaction ID or a token.
```APIDOC
## GET /transaction/verify
### Description
Verifies the status of a transaction using its unique transaction ID or a token.
### Method
GET
### Endpoint
/transaction/verify
### Parameters
#### Query Parameters
- **transaction_id** (string) - Required - The unique identifier of the transaction to verify.
- **token** (string) - Required - The token associated with the transaction to verify. (Use either `transaction_id` or `token`, not both).
### Request Example (using transaction_id)
```
GET /transaction/verify?transaction_id=TX123456789
```
### Request Example (using token)
```
GET /transaction/verify?token=abcdef12345
```
### Response
#### Success Response (200)
- **status** (string) - The current status of the transaction (e.g., "completed", "pending", "failed").
- **transaction_id** (string) - The unique transaction ID.
- **amount** (integer) - The transaction amount.
- **currency** (string) - The transaction currency.
#### Response Example
```json
{
"status": "completed",
"transaction_id": "TX123456789",
"amount": 10000,
"currency": "XOF"
}
```
```
--------------------------------
### Payment Initialization API
Source: https://docs.cinetpay.com/api/1.0-en/sdk/python
This endpoint allows you to initialize a payment transaction. You need to provide payment details such as amount, currency, transaction ID, description, and URLs for return and notification.
```APIDOC
## POST /payment/initialize
### Description
Initializes a payment transaction with CinetPay.
### Method
POST
### Endpoint
/payment/initialize
### Parameters
#### Request Body
- **amount** (integer) - Required - The amount of the transaction.
- **currency** (string) - Required - The currency code for the transaction (e.g., "XOF").
- **transaction_id** (string) - Required - A unique identifier for the transaction.
- **description** (string) - Required - A description of the transaction.
- **return_url** (string) - Required - The URL to redirect the user to after payment.
- **notify_url** (string) - Required - The URL to receive payment notifications.
- **customer_name** (string) - Optional - The name of the customer.
- **customer_surname** (string) - Optional - The surname of the customer.
### Request Example
```json
{
"amount": 10000,
"currency": "XOF",
"transaction_id": "TX123456789",
"description": "Payment for order #123",
"return_url": "https://www.example.com/return",
"notify_url": "https://www.example.com/notify",
"customer_name": "John",
"customer_surname": "Doe"
}
```
### Response
#### Success Response (200)
- **payment_url** (string) - The URL where the user can complete the payment.
- **transaction_id** (string) - The unique transaction ID.
- **status** (string) - The status of the transaction initialization.
#### Response Example
```json
{
"payment_url": "https://checkout.cinetpay.com/pay?token=abcdef12345",
"transaction_id": "TX123456789",
"status": "pending"
}
```
```
--------------------------------
### Initiate Payment Request using Javascript (Axios)
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
This snippet demonstrates how to send a POST request to the CinetPay payment API using the Axios library in Javascript. It includes setting up the request payload with transaction details and handling the API response or errors.
```javascript
var axios = require('axios');
var data = JSON.stringify({
"apikey": "",
"site_id": "",
"transaction_id": "YOUR_TRANSACTION_ID",
"amount": 34,
"currency": "USD",
"alternative_currency": "",
"description": " TEST INTEGRATION ",
"customer_id": "172",
"customer_name": "KOUADIO",
"customer_surname": "Francisse",
"customer_email": "harrissylver@gmail.com",
"customer_phone_number": "+225004315545",
"customer_address": "Antananarivo",
"customer_city": "Antananarivo",
"customer_country": "CM",
"customer_state": "CM",
"customer_zip_code": "065100",
"notify_url": "https://webhook.site/d1dbbb89-52c7-49af-a689-b3c412df820d",
"return_url": "https://webhook.site/d1dbbb89-52c7-49af-a689-b3c412df820d",
"channels": "ALL",
"metadata": "user1",
"lang": "FR",
"invoice_data": {
"Donnee1": "",
"Donnee2": "",
"Donnee3": ""
}
});
var config = {
method: 'post',
url: 'https://api-checkout.cinetpay.com/v2/payment',
headers: {
'Content-Type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
--------------------------------
### Javascript SDK Seamless Checkout
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
This section details how to use the CinetPay Javascript SDK to initiate a seamless checkout process. It includes configuration, payment details, and response handling for successful or failed transactions.
```APIDOC
## POST /checkout (via Javascript SDK)
### Description
Initiates a seamless payment checkout using the CinetPay Javascript SDK. This function handles the entire payment flow, from configuration to response handling.
### Method
Javascript Function Call (SDK)
### Endpoint
Not applicable (Client-side SDK)
### Parameters
#### Configuration (CinetPay.setConfig)
- **apikey** (string) - Required - Your unique CinetPay API key.
- **site_id** (string) - Required - Your CinetPay site ID.
- **notify_url** (string) - Required - The URL to receive payment notifications.
- **mode** (string) - Required - Payment mode ('PRODUCTION' or 'TEST').
#### Payment Details (CinetPay.getCheckout)
- **transaction_id** (string) - Required - Unique identifier for the transaction. Should not contain special characters and must be unique if parameters change.
- **amount** (number) - Required - The payment amount. Must be a multiple of 5, unless the currency is USD.
- **currency** (string) - Required - The currency code for the transaction (e.g., 'XOF'). Must match the currency authorized for your account.
- **channels** (string) - Optional - Payment channels to use (e.g., 'ALL').
- **description** (string) - Optional - A description for the payment.
- **customer_name** (string) - Optional - Customer's name.
- **customer_surname** (string) - Optional - Customer's surname.
- **customer_email** (string) - Optional - Customer's email address.
- **customer_phone_number** (string) - Optional - Customer's phone number (including prefix, e.g., '+2250504315545').
- **customer_address** (string) - Optional - Customer's address.
- **customer_city** (string) - Optional - Customer's city.
- **customer_country** (string) - Optional - ISO code of the customer's country.
- **customer_state** (string) - Optional - ISO state code of the customer's country.
- **customer_zip_code** (string) - Optional - Customer's zip code.
- **invoice_data** (object) - Optional - Additional invoice data (e.g., `{"Reste à payer":"25 000fr", "Matricule":"24OPO25", "Annee-scolaire":"2020-2021"}`).
- **lock_phone_number** (boolean) - Optional - Set to `true` to lock the phone number field.
### Request Example
```javascript
CinetPay.setConfig({
apikey: 'YOUR_API_KEY',
site_id: 'YOUR_SITE_ID',
notify_url: 'http://mondomaine.com/notify/',
mode: 'PRODUCTION'
});
CinetPay.getCheckout({
transaction_id: Math.floor(Math.random() * 100000000).toString(),
amount: 100,
currency: 'XOF',
channels: 'ALL',
description: 'Test paiement',
customer_name: "Joe",
customer_surname: "Down",
customer_email: "down@test.com",
customer_phone_number: "+2250504315545",
customer_address: "BP 0024",
customer_city: "Antananarivo",
customer_country: "CM",
customer_state: "CM",
customer_zip_code: "06510",
lock_phone_number: true,
invoice_data: {
"Reste à payer": "25 000fr",
"Matricule": "24OPO25",
"Annee-scolaire": "2020-2021"
}
});
```
### Response
#### Event Handlers
- **CinetPay.waitResponse(callback)**: Callback function executed when a payment response is received.
- **CinetPay.onError(callback)**: Callback function executed when an error occurs.
#### Response Example (within waitResponse callback)
```javascript
// data object contains payment status and details
if (data.status == "REFUSED") {
// Handle payment refusal
alert("Your payment failed");
window.location.reload();
} else if (data.status == "ACCEPTED") {
// Handle successful payment
alert("Your payment has been made successfully");
window.location.reload();
}
```
#### Error Response Example (within onError callback)
```javascript
// data object contains error details
console.log(data);
```
### Good to know
- **Amount**: The amount must be a multiple of 5, unless the currency is USD.
- **Transaction ID**: Must be unique if payment parameters are modified. Avoid special characters.
- **API Key & Site ID**: Unique keys for test and production environments. Obtain them after subscribing to a service.
- **Currency**: Transactions must be in the local currency authorized for your account (e.g., XAF for Cameroon).
- **Phone Number**: Use the format `prefix + number` (e.g., `+2250504315545`). The `lock_phone_number` parameter can be used to control user input.
```
--------------------------------
### Verify CinetPay Transaction by Token
Source: https://docs.cinetpay.com/api/1.0-en/sdk/python
Verifies the status of a CinetPay transaction using its associated token. This method requires an initialized CinetPay client and the token. The function returns the verification details for the specified token.
```python
from cinetpay_sdk.s_d_k import Cinetpay
apikey = "XXXXXXXXXXXXXXXXXX"
site_id = "XXXXXX"
client = Cinetpay(apikey,site_id)
token ="XXXXXX"
print(client.TransactionVerfication_token(token))
```
--------------------------------
### Return URL Handling
Source: https://docs.cinetpay.com/api/1.0-en/checkout/retour
After a payment, CinetPay redirects the customer to the specified return URL. This URL should be configured to accept both GET and POST requests and is used to identify the transaction and provide feedback to the user. It's crucial to note that no database processing should occur on the return URL; it's solely for redirection.
```APIDOC
## GET /return_url
### Description
Handles customer redirection back to the merchant site after a CinetPay transaction. This endpoint should accept GET requests.
### Method
GET
### Endpoint
/return_url
### Query Parameters
- **transaction_id** (string) - Required - The unique identifier for the transaction.
### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the transaction.
- **message** (string) - A user-friendly message regarding the transaction status.
#### Response Example
```json
{
"status": "success",
"message": "Your payment was successful."
}
```
## POST /return_url
### Description
Handles customer redirection back to the merchant site after a CinetPay transaction. This endpoint should accept POST requests, primarily for receiving the transaction ID.
### Method
POST
### Endpoint
/return_url
### Parameters
#### Request Body
- **transaction_id** (string) - Required - The unique identifier for the transaction.
### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the transaction.
- **message** (string) - A user-friendly message regarding the transaction status.
#### Response Example
```json
{
"status": "success",
"message": "Your payment was successful."
}
```
## Testing the Return URL
### Description
Instructions on how to test the configured return URL using an HTTP request application like Postman.
### Method
GET and POST
### Endpoint
[Your configured return_url]
### Test Steps
**For GET requests:**
1. Enter your notification URL in the request application.
2. Select the GET method and click "Send".
3. Expect a Status 200 OK.
4. Use the "preview" option to view the page.
**For POST requests:**
1. Enter your notification URL.
2. Select the POST method.
3. Set the Content-Type to `x-www-form-urlencoded`.
4. Include the **transaction_id** in the request body and click "Send".
5. Expect a Status 200 OK.
6. Use the "preview" option to view the page.
### Notes
- **Session Management**: Use the `metadata` variable during initialization to pass session information and avoid re-login issues upon return.
- **307 Redirect Errors**: If encountering 307 redirects, check server restrictions (e.g., O2switch's "Default Security" option) and disable them if necessary.
```
--------------------------------
### POST /v2/payment
Source: https://docs.cinetpay.com/api/1.0-en/checkout/initialisation
Initiates a payment transaction. This endpoint requires a POST request with payment details in the JSON body. After a successful request, a payment URL will be returned, which can be used to redirect the user to the payment counter.
```APIDOC
## POST /v2/payment
### Description
Initiates a payment transaction. This endpoint requires a POST request with payment details in the JSON body. After a successful request, a payment URL will be returned, which can be used to redirect the user to the payment counter.
### Method
POST
### Endpoint
https://api-checkout.cinetpay.com/v2/payment
### Parameters
#### Request Body
- **apikey** (string) - Required - Your CinetPay API key.
- **site_id** (string) - Required - Your CinetPay site ID.
- **transaction_id** (string) - Required - A unique identifier for the transaction.
- **amount** (number) - Required - The transaction amount.
- **currency** (string) - Required - The currency code (e.g., 'USD', 'XOF').
- **alternative_currency** (string) - Optional - An alternative currency for the transaction.
- **description** (string) - Optional - A description of the transaction.
- **customer_id** (string) - Optional - The ID of the customer.
- **customer_name** (string) - Optional - The name of the customer.
- **customer_surname** (string) - Optional - The surname of the customer.
- **customer_email** (string) - Optional - The email of the customer.
- **customer_phone_number** (string) - Optional - The phone number of the customer.
- **customer_address** (string) - Optional - The address of the customer.
- **customer_city** (string) - Optional - The city of the customer.
- **customer_country** (string) - Optional - The country code of the customer.
- **customer_state** (string) - Optional - The state of the customer.
- **customer_zip_code** (string) - Optional - The zip code of the customer.
- **notify_url** (string) - Optional - The URL to notify upon transaction completion.
- **return_url** (string) - Optional - The URL to redirect the user to after payment.
- **channels** (string) - Optional - Payment channels to use (e.g., 'ALL', 'MOBILE_MONEY').
- **metadata** (string) - Optional - Additional metadata for the transaction.
- **lang** (string) - Optional - The language for the payment page (e.g., 'FR').
- **invoice_data** (object) - Optional - Additional data for the invoice.
- **Donnee1** (string) - Optional - Invoice data field 1.
- **Donnee2** (string) - Optional - Invoice data field 2.
- **Donnee3** (string) - Optional - Invoice data field 3.
### Request Example
```json
{
"apikey": "YOUR_API_KEY",
"site_id": "YOUR_SITE_ID",
"transaction_id": "YOUR_TRANSACTION_ID",
"amount": 34,
"currency": "USD",
"alternative_currency": "",
"description": " TEST INTEGRATION ",
"customer_id": "172",
"customer_name": "KOUADIO",
"customer_surname": "Francisse",
"customer_email": "harrissylver@gmail.com",
"customer_phone_number": "+225004315545",
"customer_address": "Antananarivo",
"customer_city": "Antananarivo",
"customer_country": "CM",
"customer_state": "CM",
"customer_zip_code": "065100",
"notify_url": "https://webhook.site/d1dbbb89-52c7-49af-a689-b3c412df820d",
"return_url": "https://webhook.site/d1dbbb89-52c7-49af-a689-b3c412df820d",
"channels": "ALL",
"metadata": "user1",
"lang": "FR",
"invoice_data": {
"Donnee1": "",
"Donnee2": "",
"Donnee3": ""
}
}
```
### Response
#### Success Response (201)
- **code** (string) - The response code indicating success.
- **message** (string) - A message describing the response.
- **description** (string) - A detailed description of the transaction status.
- **data** (object) - Contains payment details.
- **payment_token** (string) - A token for the payment.
- **payment_url** (string) - The URL to redirect the user for payment.
- **api_response_id** (string) - A unique ID for the API response.
#### Response Example
```json
{
"code": "201",
"message": "CREATED",
"description": "Transaction created with success",
"data": {
"payment_token": "5df64dd9c5447739327eb88e1e4ea0ac015555cc262ea308c91acbd4e5c8fb95f4bd0bd7cad877a452f877fa6f51fe74184d00a84ab7f9",
"payment_url": "https://checkout.cinetpay.com/payment/5df64dd9c5447739327eb88e1e4ea0ac015555cc262ea308c91acbd4e5c8fb95f4bd0bd7cad877a452f877fa6f51fe74184d00a84ab7f9"
},
"api_response_id": "1632143554.8513"
}
```
#### Error Response
- **code** (string) - The error code.
- **message** (string) - A message describing the error.
- **description** (string) - A detailed description of the error.
- **api_response_id** (string) - A unique ID for the API response.
#### Response Example
```json
{
"code": "ERROR_CODE",
"message": "ERROR_MESSAGE ",
"description": "ERROR_DESCRIPTION",
"api_response_id": "RESPONSE_ID_HERE"
}
```
```