NAV
shell

Introduction

CirclePay is a platform that enables merchants to develop their projects by connecting many electronic payment gateways located in Egypt in one place with the freedom to choose the appropriate payment method.

Integration Process

To consume CirclePay Apis you should:

1. Add account key and token to your platform

2. Create a merchant:
 2.1. POST /merchants/create
 2.2. POST /merchants/send/otp
 2.3. POST /merchants/verify

3. List Payment Gateways in the system:
 3.1. GET /payment/gateway/list

4. Enable Payment Gateway for a merchant:
 4.1. GET /merchants/payment/gateway/enable/{payment_gateway_id}

5. List Payment Method in the System:
 5.1. GET /payment/methods/list/{paymentGatewayId}

6. Enable Payment Method:
 6.1. GET /merchants/payment/method/enable/{payment_method_id}

7. Create invoice:
 7.1. POST /invoice/create

8. Pay Invoice:
 8.1. POST /invoice/pay

9. List Transactions:
 9.1. POST /payment/list

Payment Gateway

To process online transactions, you will need both a payment gateway and a payment method.

A payment gateway is the technology that captures and transfers payment data from the customer to the acquirer.

A payment method is a way that customers pay for a product or service.

List Payment Gateways

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     'https://circlepay.ai/apis/payment/gateway/list'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "id": "610b2c486df621209c85215a",
      "name": "MyFatoorah"
    },
    {
      "id": "613927082de6eb5dc061d516",
      "name": "Fawry"
    },
  ],
  "isError": false
}

Retrieves all payment gateways to the merchant.

Parameters

No Parameters.

Returns

Returns payment gateway list.

Retrieve a Payment Gateway

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     'https://circlepay.ai/apis/payment/gateway/get/{payment_gateway_ID}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "id": "610b2c486df621209c85215a",
      "name": "MyFatoorah"
    }
  ],
  "isError": false
}

Retrieves a specific payment gateway.

Parameter Type Required Default Description
payment_gateway_ID String required      - Unique identifier for the payment gateway object.

Returns

Return a payment gateway object.

Payment Methods

A payment method is a way that customers pay for a product or service. CirclePay gives customers the freedom to choose between payment methods like: cash, credit cards, prepaid cards, debit cards, or mobile payments.

MyFatoorh Fawry Paymob
Visa Visa Visa
MasterCard MasterCard MasterCard
meeza meeza Kiosk Payments
Mobile Wallet E-wallet Payment Cash Collection
ValU Reference Number ValU
SADAD ValU Mobile Wallets
mada SOUHOOLA
ApplePay
Knet
American express

List a Payment Methods

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     'https://circlepay.ai/apis/payment/methods/list/{paymentGatewayId}
'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "id": "61bf27e54b8bcfac495f997c",
      "name": "Wallet",
      "gateway_id": "610b2c486df621209c85215a"
    },
    {
      "id": "61c0401b253faaefc6af1993",
      "name": "Meeza",
      "gateway_id": "610b2c486df621209c85215a"
    }
  ],
  "isError": false
}

Retrieves all payment methods of the specific gateway.

Parameter Type Required Default Description
payment_gateway_ID String required      - Unique identifier for the payment gateway object.

Returns

Returns a payment methods list.

Retrieve a Payment Method

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     'https://circlepay.ai/apis/PaymentMethod/get/{payment_method_id}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "id": "610b2c486df621209c85215c",
      "name": "AMEX",
      "gateway_id": "610b2c486df621209c85215a"
    }
  ],
  "isError": false
}

Retrieves a specific payment method.

Parameter Type Required Default Description
payment_method_ID String required      - Unique identifier for the payment method object.

Returns

Returns a payment method object.

Merchants

Merchant is the person or company engaged in the business of selling products or services. For example, wholesaler or retail store owner.

Create a Merchant

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d first_name="Ahmed"
     -d last_name="Khaled"
     -d email="ahmedkahled@gmail.com"
     -d mobile_number="+201001414133"
     -d Business_Name="E-commerce"
     -d Business_Address="El-maadi"
     -d callback_url="https://bit.ly/3KXl3iA"
     'https://circlepay.ai/apis/merchants/create'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "merchant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJpZCI6Nzk3LCJpc1ZlcmlmaWVkIjpmYWxz"
    }
  ],
  "isError": false
}

This endpoint helps you to create new merchant.

Parameter Type Required Default Description
first_name String required      - The merchant's first name.
last_name String required      - The merchant's last name.
email String required      - The merchant's email.
mobile_number String required      - The merchant's phone number.
Business_Name String required      - The business name.
Business_Address String required      - The business address.
callback_url String required      - A callback URL will be invoked by the API method you're calling after it's done.

Returns

Returns the merchant id if the merchant created successfully. Returns an error if create parameters are invalid.

Callback Service

You as a platform or a merchant will implement or develop this callback so you can know transaction status. The specification of this callback is made by CirclePay.

Parameter Type Required Default Description
transaction_id String required      - Unique identifier of transaction object.
transaction_type Integer required      - The type of transaction (1 for payments, 2 for refund).
transaction_status String required      - Can be used to track the state or condition of the transaction record for example, "pending".
payment_gateway_name String required      - The name of payment gateway.
payment_method_name String required      - The name of payment method.

Returns

Http response will be 200 in success, else it will be other http response.

Retrieve a Merchant

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     'https://circlepay.ai/apis/merchants/get'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "first_name": "ahmed",
      "last_name": "khaled",
      "email": "medy@circlepay.ai",
      "mobile_number": "+201005081863",
      "business_name": "E-commerceEgypt",
      "business_address": "El-maadi",
      "refund_policy": null,
      "shipping_policy": null,
      "status": "1",
      "merchant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Mjk4LCJpc1Zlcmlm"
    }
  ],
  "isError": false
}

Retrieves a specific merchant.

Parameters

No Parameters.

Returns

Returns the merchant object for a valid identifier.

Update a Merchant

curl -X PUT --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d first_name="ahmed"
     -d last_name="khaled"
     -d email="ahmed@gmail.com"
     -d mobile_number="+201001215155"
     -d business_name="ecommerce"
     -d business_address="el-maadi"
     -d callback_url="https://bit.ly/3KXl3iA"
     'https://circlepay.ai/apis/merchants/update'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "first_name": "ahmed",
     "last_name": "khaled",
     "email": "ahmed@gmail.com",
     "mobile_number": "+201001212155",
     "business_name": "ecommerce",
     "business_address": "el-maadi",
     "refund_policy": "Refunds and exchanges, right to cancel your order",
     "shipping_policy": "Original sales receipt must accompany returns",
     "status": "1",
     "merchant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIsImZpcnN0Tm"
    }
   ],
   "isError" : False
}

Updates the specified merchant by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameter Type Required Default Description
first_name String required      - The merchant's first name.
last_name String required      - The merchant's last name.
email String required      - The merchant's email.
Business_Name String required      - The business name.
Business_Address String required      - The business address.
callback_url String required      - A callback URL will be invoked by the API method you're calling after it's done.

Returns

Returns the merchant object if the update succeeded. Returns an error if update parameters are invalid.

List all merchants

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/list'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "first_name": "ahmed",
     "last_name": "khaled",
     "email": "ahmed@gmail.com",
     "mobile_number": "+201001212155",
     "business_name": "ecommerce",
     "business_address": "el-maadi",
     "refund_policy": "Refunds and exchanges, right to cancel your order",
     "shipping_policy": "Original sales receipt must accompany returns",
     "status": 2
    },
    {
     "first_name": "ibrahim",
     "last_name": "salah",
     "email": "ibrahim@gmail.com",
     "mobile_number": "+201001812155",
     "business_name": "nike",
     "business_address": "el-maadi",
     "refund_policy": "Refunds and exchanges, right to cancel your order",
     "shipping_policy": "Original sales receipt must accompany returns",
     "status": 0
    }
   ],
    "isError" : False
}

Retrieves all merchants.

Parameters

No Parameters.

Returns

Returns an array. Each entry in the array is a separate user object.This request should never return an error.

Enable gateway

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/payment/gateway/enable/{payment_gateway_id}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "payment_gateway_id": "610b2c486df621209c85215b"
    }
  ],
  "isError": false
}

This endpoint enable specific payment gateway.

Parameter Type Required Default Description
payemnt_gateway_id String required      - Unique identifier for the payment gateway object.

Returns

Returns id of enabled payment gateway.

Disable gateway

curl -X DELETE --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/payment/gateway/disable/{payment_gateway_id}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "payment_gateway_id": "610b2c486df621209c85215b"
    }
  ],
  "isError": false
}

This endpoint disable specific gateway and it's related payment methods.

Parameter Type Required Default Description
payment_gateway_ID String required      - Unique identifier for the payment gateway object.

Returns

Returns the id of disabled payment gateway.

List payment gateways

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/payment/gateway/list'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
[
    {
      "id": "610b2c486df621209c85215a",
      "name": "MyFatoorah",
      "status": false,
      "config": {
        "id": 1,
        "apiKey": "RY6GXFd6KJKBZ98PHPLJOpmXthqkppqM3FF79cbUhv_MACpIAQ4LD3R5MemgqnA3BgVtEa-NeIItV4fFawY4XalaXuRKqcYM2MXIaYbvJnudshMQSOrQwWcvetktUzdNxQxUsoPAu6vEKlynpVkf0VYqr-9SLYSfvxKiMe6rnqGmtwMC5fcUdkfgrVznxCTr4B7dqQX09vU1_YC_gFzLxQPTP5z3Juum1JAxxv8kJ7RShclqMcWM_g2tNWzy3omqGqUflWobBBe3ebdiLtIF9pzYTqOvHsVi6k9HM6AnKR79hTQbfVICTacdhvNGKhy6HbjsaShDfI6gg4DgZ5dBjOboth9lPtqSb2OBB_3vbvUjyeOa71I5DbyEWx4Nx96luiybyvjf0ig8_yAs5HeuPz2BPPeglaila0fhW79KsKfMs9CBjKLDsJJ4EPMR6TALwefsBebOPLX6fqUvYzAuu4T8lUTAl1LlV_QeI1sc6IAc5KmkHzodRw-lQdq201a9SG6qfOH61QP_hQwS98tObIdBqQAhu2_oMNDOhYQ9kTVrSgQTrCkYTmhDI3xTp8TA09OtH7I80g-gUVf_y_zYEbJXomFVrRcPHHrt9tl1DJ9wAiaL6P9o1QrEVf7zAmLn8FedgGLdeBjOcIFjcCCQd0eLQZxTC7krBHYAXZeZbW0-RfaD",
        "signature": "",
        "merchantCode": "",
        "merchantRefNum": ""
      }
    },
    {
      "id": "610b2c486df621209c85215b",
      "name": "PayMob",
      "status": false,
      "config": {
        "CARD": {
          "iframeID": "64969",
          "integrationID": "33483"
        },
        "CASH": {
          "iframeID": "",
          "integrationID": ""
        },
        "Kiosk": {
          "iframeID": "",
          "integrationID": "107439"
        },
        "Wallet": {
          "iframeID": "",
          "integrationID": "104351"
        },
        "apiKey": "ZXlKaGJHY2lPaUpJVXpVeE1pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SndjbTltYVd4bFgzQnJJam94TkRnM01Td2libUZ0WlNJNkltbHVhWFJwWVd3aUxDSmpiR0Z6Y3lJNklrMWxjbU5vWVc1MEluMC4ybzdQVld2UHJTR0MzR0xCaDF4VzZjQWhiNUVFMS1uN3lIeGVTTFNENVF5OFlHeDBQQzY3OGM5dXJnZ2R4MHZSSDR5NHdHcG01VXM4NmJ1bWNMeU4xdw==",
        "SUHOOLA": {
          "iframeID": "326757",
          "integrationID": "33483"
        }
      }
    },
    {
      "id": "613927082de6eb5dc061d516",
      "name": "Fawry",
      "status": false,
      "config": {
        "id": 4,
        "apiKey": "f19f9720-6462-466d-b9bc-4128f772bafb",
        "signature": "as",
        "merchantCode": "siYxylRjSPx5Hw/oRBKFwQ==",
        "merchantRefNum": "as"
      }
    }
  ],
  "isError" : False
}

This endpoint list merchant's payment gateways.

Parameters

No Parameters.

Returns

Returns the payment gateways list for merchant.

Enable payment method

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/payment/method/enable/{payment_method_ID}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "payment_method_id": "610b2c486df621209c85215c"
    }
  ],
  "isError": false
}

This endpoint enable specific payment method.

Parameter Type Required Default Description
payment_method_ID String required      - Unique identifier for the payment method object.

Returns

Returns id of enabled payment method.

Disable payment method

curl -X DELETE --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/payment/method/enable/{payment_method_ID}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "payment_method_id": "610b2c486df621209c85215c"
    }
  ],
  "isError": false
}

This endpoint disable specific payment method.

Parameter Type Required Default Description
payment_method_ID String required      - Unique identifier for the payment method object.

Returns

Returns id of the disabled payment method.

List payment methods

curl -X GET --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/merchants/payment/method/list'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
      [ 
        {
          "id": "610b2c496df621209c852168",
          "name": "Visa",
          "gateway_id": "1",
          "status": true
        },
        {
          "id": "610b2c496df621209c8521we",
          "name": "MasterCard",
          "gateway_id": "1",
          "status": 0
        }
      ],
       "isError" : False
}

This endpoint list allowed payment methods to the merchant.

Parameters

No parameters.

Returns

Returns a payment methods list of the merchant.

Send OTP

curl -X POST --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     -d merchant_mobile="+201012794709"
     -d country_code="+20"
     'https://circlepay.ai/apis/merchants/send/otp'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
      "status": true
    }
   ],
   "isError" : False
}

This endpoint sends the OTP to validate the merchant.

Parameter Type Required Default Description
merchant_mobile String required      - The merchant's mobile number.
country_code String required      - The country code for example, the country code for egypt is +20

Returns

Returns the status (true or false).

Verify Merchant

curl -X POST --header 'Content-Type: application/json'
     --header 'Accept: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     'https://circlepay.ai/apis/merchants/verify'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" : null,
 "isError" : False,
}

This endpoint allow you to verify merchant.

Parameters

Parameter Type Required Default Description
Merchant_mobile String required      - Merchant's mobile number.
otp String required      - One-time password (OTP) systems provide a mechanism for logging on to a network or service using a unique password that can only be used once.

Returns

Verify merchant mobile to compelete registration.

Customers

Create a Customer

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d First_Name="Ahmed"
     -d Last_Name="Khaled"
     -d email="ahmedkahled@gmail.com"
     -d mobile_number="+201001616166"
     -d country="Egypt"
     -d city="cairo"
     'https://circlepay.ai/apis/customer/create'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {  
       "customer_mobile_number": "+201001212144"
    }
   ],
    "isError" : False
}

This endpoint helps you to create new customer.

Parameter Type Required Default Description
First_Name String required      - The customer's first name.
Last_Name String required      - The customer's last name.
email String required      - The customer's email.
mobile_number String required      - The customer's phone number.
country String required      - The customer's country.
governorate String required      - The customer's governorate.
city String required      - The customer's city.
address String required      - The customer's address.
apt_num Numeric required      - The customer's apartment number.

Returns

Returns the customer mobile number if the customer's creation succeeded. Returns an error if parameters are invalid.

Update a Customer

curl -X PUT --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d First_Name="Ahmed"
     -d Last_Name="Khaled"
     -d email="ahmedkahled@gmail.com"
     -d mobile_number="+201001717177"
     -d country="Egypt"
     -d city="cairo"
     'https://circlepay.ai/apis/customer/update'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {  
       "customer_mobile_number": "+201001212144"
    }
   ],
    "isError" : False
}

This endpoint helps you to update customer details.

Parameter Type Required Default Description
First_Name String required      - The customer's first name.
Last_Name String required      - The customer's last name.
email String required      - The customer's email.
mobile_number String required      - The customer's phone number.
country String required      - The customer's country.
governorate String required      - The customer's governorate.
city String required      - The customer's city.
address String required      - The customer's address.
apt_num Numeric required      - The customer's apartment number.

Returns

Returns the customer mobile number if the customer's update succeeded. Returns an error if parameters are invalid.

Retrieve a customer

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/customer/get/{customer_mobile_number}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {  
       "first_name": "Ibrahim",
       "last_name": "Salah",
       "email": "ibrahim@gmail.com",
       "mobile_number": "+201001212144",
       "country": "Egypt",
       "governorate": "cairo",
       "city": "nasr",
       "address": "72 gamal st",
       "apt_num": "5"
    }
   ],
    "isError" : False
}

Retrieves a specific customer.

Parameter Type Required Default Description
customer_mobile_number String required      - Customer's mobile number.

Returns

Returns the Customer object for a valid mobile number.

List all customers

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/customer/list'

The above command returns JSON structured like this:


{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {  
       "first_name": "Ibrahim",
       "last_name": "Salah",
       "email": "ibrahim@gmail.com",
       "mobile_number": "+201001212144",
       "country": "Egypt",
       "governorate": "cairo",
       "city": "nasr",
       "address": "72 gamal st",
       "apt_num": "5"
    },
    {  
       "first_name": "Tamer",
       "last_name": "Aly",
       "email": "taly@hotmail.com",
       "mobile_number": "+20133444144",
       "country": "Egypt",
       "governorate": "alex",
       "city": "nasr",
       "address": "12 roshdy st",
       "apt_num": "35"
    }
   ],
    "isError" : False
}

Retrieves a list of your customers.

Parameters

No parameters.

Returns

Returns customer list, If no more customers are available, the resulting array will be empty. This request should never return an error.

Payment Link

curl -X POST --header 'Accept: application/json'
      --header 'Content-Type: application/json'
      --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
      --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
      --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
        -d value= 18000
        -d currency="EGP"
        -d enable_Survey= 0
        -d expiry_Date= 2022-08-22
        -d description="new iphone 12"
        -d status= 1
        -d shippingPolicyFlag= 0
        -d refundPolicyFlag= 1
        -d shippingPolicyDetails= "For calculated shipping rates: Shipping charges for your order will be calculated and displayed at checkout."
        -d refundPolicyDetails="You can refund your money within 30 days"
        -d comments=""
        -d name="iphone 12"
        -d getCustAddress= 0
        'https://circlepay.ai/apis/paymentlink/create'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
     {
        "Link": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        "payment_link_url": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
      }
    ],
     "isError" : False
}

Create a new payment link, so customer can purchase the product from merchant.

Parameter Type Required Default Description
value Float required      - The price of the product.
Currency LOV optional      - The currency used in transaction (predefined currency list).
enable_Survey Boolean optional      - This option helps merchant to add survey to checkout.
expiry_Date Date required      - The payment link expiry date.
description String required      - The description of products that will be included in the transaction.
name String required      - The name of the product.
status Boolean optional      - The status of payment link (1/0 - active/inactive).
shippingPolicyFlag Boolean optional      - This option helps merchant to add shipping policy section in checkout ( 1/0 - enable/disable).
refundPolicyFlag Boolean optional      - This option helps merchant to add refund policy section in checkout ( 1/0 - enable/disable).
shippingPolicyDetails String optional      - This is the shipping policy details (will exist if shippingPolicyFlag is 1).
refundPolicyDetails String optional      - This is the refund policy details (will exist if refundPolicyFlag is 1).
comments String optional      - The comments of the merchant.
getCustAddress Boolean optional      - To get customer address in the checkout (1/0 - enable/disable).

Returns

Returns a payment link url, and returns an error otherwise.

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
       --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
       --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/paymentlink/get/{payment_link_url}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
      {
        "payment_link_url": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        "value": 18000,
        "currency": "EGP",
        "enable_Survey": 0,
        "expiry_Date": 2022-08-22,
        "description": "new iphone 12",
        "status": 1,
        "shippingPolicyFlag": 0,
        "refundPolicyFlag": 1,
        "shippingPolicyDetails": "For calculated shipping rates: Shipping charges for your order will be calculated and displayed at checkout.",
        "refundPolicyDetails": "You can refund your money within 30 days",
        "comments": "",
        "name": "iphone 12",
        "getCustAddress": 0
      }
    ],
     "isError" : False
}

To Retrieve the payment link object, either payment_link_ID or payment_link_url is included.

Parameters

No parameters

Returns

Returns a payment link object and payment link url.

curl -X PUT --header 'Accept: application/json'
      --header 'Content-Type: application/json'
      --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
      --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
      --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
        -d payment_link_url= "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        -d value= 18000
        -d currency="EGP"
        -d enable_Survey= 0
        -d expiry_Date= 2022-08-22
        -d description="new iphone 12"
        -d status= 1
        -d shippingPolicyFlag= 0
        -d refundPolicyFlag= 1
        -d shippingPolicyDetails= "For calculated shipping rates: Shipping charges for your order will be calculated and displayed at checkout."
        -d refundPolicyDetails="You can refund your money within 30 days"
        -d comments=""
        -d name="iphone 12"
        -d getCustAddress= 0
        'https://circlepay.ai/apis/paymentlink/update'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
     {
        "Link": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        "payment_link_url": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
      }
    ],
     "isError" : False
}

Update the details of existing payment link.

Parameter Type Required Default Description
payment_link_url String required      - The payment link url.
value Float required      - The price of the product.
Currency LOV optional      - The currency used in transaction (predefined currency list).
enable_Survey Boolean optional      - This option helps merchant to add survey to checkout.
expiry_Date Date required      - The payment link expiry date.
description String required      - The description of products that will be included in the transaction.
name String required      - The name of the product.
status Boolean optional      - The status of payment link (1/0 - active/inactive).
shippingPolicyFlag Boolean optional      - This option helps merchant to add shipping policy section in checkout ( 1/0 - enable/disable).
refundPolicyFlag Boolean optional      - This option helps merchant to add refund policy section in checkout ( 1/0 - enable/disable).
shippingPolicyDetails String optional      - This is the shipping policy details (will exist if shippingPolicyFlag is 1).
refundPolicyDetails String optional      - This is the refund policy details (will exist if refundPolicyFlag is 1).
comments String optional      - The comments of the merchant.
getCustAddress Boolean optional      - To get customer address in the checkout (1/0 - enable/disable).

Returns

Returns a payment link url, and returns an error otherwise.

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
       --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
       --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/paymentlink/list/{customer_mobile}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
      {
        "payment_link_url": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        "value": 18000,
        "currency": "EGP",
        "enable_Survey": 0,
        "expiry_Date": 2022-08-22,
        "description": "new iphone 12",
        "status": 1,
        "shippingPolicyFlag": 0,
        "refundPolicyFlag": 1,
        "shippingPolicyDetails": "For calculated shipping rates: Shipping charges for your order will be calculated and displayed at checkout.",
        "refundPolicyDetails": "You can refund your money within 30 days",
        "comments": "",
        "name": "iphone 12",
        "getCustAddress": 0
      },
      {
        "payment_link_url": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        "value": 12000,
        "currency": "EGP",
        "enable_Survey": 0,
        "expiry_Date": 2022-08-22,
        "description": "new samsung phone",
        "status": 1,
        "shippingPolicyFlag": 0,
        "refundPolicyFlag": 1,
        "shippingPolicyDetails": "For calculated shipping rates: Shipping charges for your order will be calculated and displayed at checkout.",
        "refundPolicyDetails": "You can refund your money within 30 days",
        "comments": "",
        "name": "samsung phone",
        "getCustAddress": 0
      }
    ],
     "isError" : False
}

To Retrieve the payment link object list.

Parameter Type Required Default Description
customer_mobile Numeric optional      - Customer's mobile number.
Filter Object optional      - payment link list returned based on this filter object.

Returns

Returns a payment link object list. Otherwise error will show.

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
       --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
       --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d payment_link.link= "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125"
     -d customer Object={}
     -d payment_method_id="610b2c496df621209c852168"
     -d coupon_code=""
     'https://circlepay.ai/apis/payPaymentLink/'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
      {

      }
    ],
     "isError" : False
}

To execute the payment link or invoice.

Parameter Type Required Default Description
payment_link.link String optional      - Customer's mobile number.
Filter String optional      - payment link list returned based on this filter object.

Returns

curl -X DELETE --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/paymentlink/deactive/{payment_link_url}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
     {}
    ],
     "isError" : False
}

To deactive the payment link.

Parameter Type Required Default Description
payment_link_url String required      - The payment link url.

Returns

Deactivate an active payment link. This will show an error page "Payment Link isn't available". Otherwise error will show.

Payment

Get a payment

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/payment/get/{transactionId}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
     {
        "id": 2,
        "transaction_id": 5,
        "external_ref_id": 2,
        "init_date": 2022-02-22,
        "update_date": 2022-02-23,
        "customer_mobile": "+201101212888",
        "status": "initialized",
        "payment_link_url": "",
        "invoice_num": "CIR_INV_1643670030264",
        "value": 99.0,
        "net_fees": 1.0,
        "currency": "EGP",
        "payment_method_id": "610b2c496df621209c852162",
        "payment_method_name": "MasterCard",
        "payment_gateway_name": "MyFatoorh"
      }
    ],
     "isError" : False
}

Retrieves the details of an existing payment.

Parameter Type Required Default Description
transaction_id String required      - Unique identifier for the payment object.

Returns

Returns a payment object if a valid identifier was provided, and returns an error otherwise.

List all payments

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/payment/list'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
      {
        "id": 1,
        "transaction_id": 6,
        "external_ref_id": 3,
        "init_date": 2022-02-22,
        "update_date": 2022-02-23,
        "customer_mobile": "+201001212888",
        "status": "pending",
        "payment_link_url": "https://bit.ly/3KXl3iA",
        "invoice_num": "",
        "value": 99.0,
        "net_fees": 1.0,
        "currency": "EGP",
        "payment_method_id": "610b2c496df621209c852168",
        "payment_method_name": "Visa",
        "payment_gateway_name": "MyFatoorh"
      },
      {
        "id": 2,
        "transaction_id": 5,
        "external_ref_id": 2,
        "init_date": 2022-02-22,
        "update_date": 2022-02-23,
        "customer_mobile": "+201101212888",
        "status": "initialized",
        "payment_link_url": "",
        "invoice_num": "CIR_INV_1643670030264",
        "value": 99.0,
        "net_fees": 1.0,
        "currency": "EGP",
        "payment_method_id": "610b2c496df621209c852162",
        "payment_method_name": "MasterCard",
        "payment_gateway_name": "MyFatoorh"
      }
    ],
     "isError" : False
}

Retrieves all payments.

Parameters

No parameters

Returns

Returns a payment list which has the details of the payment like: status, amount paid and payment method.

Refund

Allows you to refund a charge that has previously been created but not yet refunded.

Request a refund

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/refund/request'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "refund_id": "2"
    }
   ],
    "isError" : False
}

This endpoint helps you to request refund.

Parameter Type Required Default Description
transaction_id Integer required      - Unique identifier for the transaction object.

Returns

Returns the refund id. Status in refund object will be in pending state.

List all refunds

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/refund/list'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
     {
        "refund_id": "1",
        "external_ref_id": 2,
        "init_date": 2022-02-22,
        "update_date": 2022-02-23,
        "value": 40.0,
        "transaction_id": 3,
        "status": "pending"
     },
     {
        "refund_id": "2",
        "external_ref_id": 3,
        "init_date": 2022-02-22,
        "update_date": 2022-02-23,
        "value": 90.0,
        "transaction_id": 3,
        "status": "paid"
     }
    ],
    "isError" : False
}

List refund objects.

Parameters

No parameters

Returns

Returns refund object list. If no more refunds are available, the resulting array will be empty.

Get refund

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/refund/get/{refundId}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "refund_id": "2",
     "external_ref_id": 3,
     "init_date": 2022-02-22,
     "update_date": 2022-02-23,
     "value": 90.0,
     "transaction_id": 3,
     "status": "paid"
    }
   ],
    "isError" : False
}

Retrieves the refund object.

Parameter Type Required Default Description
refund_id String required      - Unique identifier for the refund object.

Returns

Returns refund object if a valid refund id is provided.

Invoice

An invoice is an itemized list that records the products or services you provided to your customers, the total amount due, and a method for them to pay you for those items or services. Invoices can be paid in one payment or in installments.

Create an invoice

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d "invoice[customer_mobile]"="+201012794709"
     -d "invoice[due_date]"="03-03-2023"
     -d "invoice[items:[{name: "phone", description: "", quantity: 8, price:12000}]]"
     'https://circlepay.ai/apis/invoice/create'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "invoice_number": "CIR_INV_16436703344261",
     "invoice_url" : "(base_checkout_url)+payment_link_url"
    }
   ],
    "isError" : False
}

This endpoint creates an invoice for a given customer. The invoice created will be in "pending" status.

Parameter Type Required Default Description
invoice Object required      - The details of the invoice object.

The table below contains invoice object attributes.

Parameter Type Required Default Description
invoice_number String optional      - The invoice number.
items Array required      - Array of item object which has the details of items in invoice for example: name,description,quantity and price.
customer_mobile String required      - The customer mobile number.
status Integer optional      - The status of invoice for example: 0 means Due, 1 means Over_Due, 2 means Paid, 3 means Deactivated.
create_date Date optional      - The creation date of invoice.
due_date Date required      - The due date of invoice which is the latest payment can be made on an invoice or debt before it's considered overdue.
pref_payment_method String optional      - The preferred payment method and it's related payment gateway for example: CARD/PayMob means method_name/gateway_name.
shipping_fees Float optional      - The shipping fees on invoice's items.
discount_value Float optional      - The discount value on total cost of items.
discount_type String optional      - The discount type, it can be value or percent.
discount_value_calculated Float optional      - The discount value calculated if the discount type is percent.
tax Float optional      - The tax in percent.
tax_value Float optional      - The calculated tax amount.
shipping_policy String optional      - The shipping policy contains potential delays due to a high volume of orders or postal service problems that are outside of your control, Domestic Shipping Rates and Estimates, local delivery policy and international shipping policy.
return_policy String optional      - The rules a retailer or merchant creates to manage how customers return and exchange unwanted merchandise they purchased for example, Amazon.com and most sellers on Amazon.com offer returns for items within 30 days of receipt of shipment.
extra_notes String optional      - The notes or comments to make invoice more clear.

Returns

Returns invoice number and invoice url.

Create an invoice V2

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d "customer[First_Name]"="Ibrahim"
     -d "customer[Last_Name]"="Salah"
     -d "customer[mobile_number]"=+201012794709
     -d "invoice[due_date]"=03-03-2023
     -d "invoice[items]= [{name: iphone, description: "", quantity: 8, price:12000}]]
     'https://circlepay.ai/apis/invoice/createV2'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "invoice_number": "CIR_INV_16436703344261",
     "invoice_url" : "(base_checkout_url)+payment_link_url",
     "transaction_id": 43536356353
    }
   ],
    "isError" : False
}

Create a new invoice: V2 API, this gets all the required information from the client platform and conducts the three steps of:

1- create customer
2- create invoice
3- pay invoice

Parameter Type Required Default Description
invoice Object required      - The details of the invoice object.

The table below contains invoice object attributes.

Parameter Type Required Default Description
invoice_number String optional      - The invoice number.
items Array required      - Array of item object which has the details of items in invoice for example: name,description,quantity and price.
customer_mobile String required      - The customer mobile number.
status Integer optional      - The status of invoice for example: 0 means Due, 1 means Over_Due, 2 means Paid, 3 means Deactivated.
create_date Date optional      - The creation date of invoice.
due_date Date required      - The due date of invoice which is the latest payment can be made on an invoice or debt before it's considered overdue.
pref_payment_method String optional      - The preferred payment method and it's related payment gateway for example: CARD/PayMob means method_name/gateway_name.
shipping_fees Float optional      - The shipping fees on invoice's items.
discount_value Float optional      - The discount value on total cost of items.
discount_type String optional      - The discount type, it can be value or percent.
discount_value_calculated Float optional      - The discount value calculated if the discount type is percent.
tax Float optional      - The tax in percent.
tax_value Float optional      - The calculated tax amount.
shipping_policy String optional      - The shipping policy contains potential delays due to a high volume of orders or postal service problems that are outside of your control, Domestic Shipping Rates and Estimates, local delivery policy and international shipping policy.
return_policy String optional      - The rules a retailer or merchant creates to manage how customers return and exchange unwanted merchandise they purchased for example, Amazon.com and most sellers on Amazon.com offer returns for items within 30 days of receipt of shipment.
extra_notes String optional      - The notes or comments to make invoice more clear.
Parameter Type Required Default Description
customer Object required      - The details of the customer object.

The table below contains customer object attributes.

Parameter Type Required Default Description
First_Name String required      - The customer's first name.
Last_Name String required      - The customer's last name.
email String optional      - The customer's email.
mobile_number String required      - The customer's phone number.
country String optional      - The customer's country.
governorate String optional      - The customer's governorate.
city String optional      - The customer's city.
address String optional      - The customer's address.
apt_num Numeric optional      - The customer's apartment number.

Returns

Returns invoice number, invoice Url and transaction id.

Retrieve an invoice

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/invoice/get/{invoice_number}'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "invoice_number": "CIR_INV_1643670030261",
     "items": [{"name":"shoe","description":"","quantity": 4,"price":90.0}],
     "customer_mobile": "+201001212333",
     "status": 1,
     "create_date": 2022-12-20,
     "due_date": 2022-12-25,
     "pref_payment_method": "CARD/PayMob",
     "shipping_fees": 4.0,
     "discount_value": 11.0,
     "discount_type": "percent",
     "discount_value_calculated": 9.9,
     "tax": 10.0,
     "tax_value": 9.0,
     "shipping_policy": "shipping options you offer (overnight, standard, air mail, international)",
     "return_policy": "Amazon.com and most sellers on Amazon.com offer returns for items within 30 days of receipt of shipment.",
     "extra_notes":
    }
 ],
 "isError" : False
}

Retrieves the invoice with the given invoice number.

Parameter Type Required Default Description
invoice_number String required      - The invoice number.

Returns

Returns an invoice object if a valid invoice number was provided. Returns an error otherwise.

list invoices

curl -X GET --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/invoice/list/{customer_mobile}'

The above command returns JSON structured like this:

List the invoices

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
   [
    {
     "invoice_number": "CIR_INV_1643670030261",
     "items": [{"name":"shoe","description":"","quantity": 4,"price":90.0}],
     "customer_mobile": "+201001212333",
     "status": 1,
     "create_date": 2022-12-20,
     "due_date": 2022-12-25,
     "pref_payment_method": "CARD/PayMob",
     "shipping_fees": 4.0,
     "discount_value": 11.0,
     "discount_type": "percent",
     "discount_value_calculated": 9.9,
     "tax": 10.0,
     "tax_value": 9.0,
     "shipping_policy": "shipping options you offer (overnight, standard, air mail, international)",
     "return_policy": "Amazon.com and most sellers on Amazon.com offer returns for items within 30 days of receipt of shipment.",
     "extra_notes":
    }
  ],
   "isError" : False
}

This endpoint list invoices for a given customer.

Parameter Type Required Default Description
customer_mobile String optional      - Customer's mobile number.
Filter String optional      - invoices list returned based on this filter object.

Returns

Returns list of invoice objects.

Delete an invoice

curl -X DELETE --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     'https://circlepay.ai/apis/invoice/delete/{invoice_number}'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": "",
  "data": [
    {
      "invoice_number": "CIR_INV_1645465416865"
    }
  ],
  "isError": false
}

Delete an invoice ONLY IF the invoice has no transactions.

Parameter Type Required Default Description
invoice_num String required      - Invoice's number.

Returns

Returns the deleted invoice number.

Pay an invoice

curl -X POST --header 'Accept: application/json'
     --header 'Content-Type: application/json'
     --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
     --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
     --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
     -d invoice_number="CIR_INV_16436702430261"
     'https://circlepay.ai/apis/invoice/pay'

The above command returns JSON structured like this:

{
  "message": "Successful",
  "errorCode": 0,
  "details": null,
  "data": [
    {
      "transaction_id": "1645895596175",
      "invoice_url": "https://staging.circlepay.ai/payment/make-payment/ddb411b2b2ecca4508ec1645465416853/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJxdWVyeVBhcmFtcyI6Ij9zdGVwPTMmT1BFeHRlcm5hbD0xNjQ1ODk1NTk2MTc1JnNlbGVjdGVkUGF5bWVudE1ldGhvZD1DQVJEJnNlbGVjdGVkUGF5bWVudEdhdGV3YXk9UGF5TW9iJnNvdXJjZT1leHRlcm5hbCIsImlhdCI6MTY0NTg5NTU5Nn0.c4526On6Nk7KgaIRaarolHnC5GXwvPC8ISnXbTLu6nI"
    }
  ],
  "isError": false
}

Pay an invoice.

Parameter Type Required Default Description
invoice_number String required      - Invoice's number.
customer_mobile String optional      - The customer mobile number.
payment_method_id String optional      - The unique identifier of payment method.

Returns

Pay the invoice if a valid invoice number was provided. Returns an error otherwise.

Direct Payment

Create a Direct Payment

curl -X POST --header 'Accept: application/json'
      --header 'Content-Type: application/json'
      --header 'account_key: de40f1f2-98a8-32bd-bc2c-96280c7b4b6b'
      --header 'account_token: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0J'
      --header 'merchant_token: Bearer 402880824ff933a4014ff9345d7c0002'
        -d customer= {"first_name": "ibrahim", "last_name": "salah", "mobile_number": 01011111111, "email": ""}
        -d directPayment={"comments": "", "description": "", "expiryDate": 22-09-2022,
        "getCustAddress": 0, "name": "iphone", "refundPolicyDetails":"", "refundPolicyFlag": 0, "shippingPolicyDetails": "", "shippingPolicyFlag":0, "value": 18000}
        -d payment_gateway_id= "610b2c486df621209c85215b"
        -d payment_method_id= "610b2c496df621209c852162"
        'https://circlepay.ai/apis/directPayment/create'

The above command returns JSON structured like this:

{
 "message" : "Successful",
 "errorCode" : 0,
 "details" : "",
 "data" :
    [
     {
        "url": "checkout.circlepay.ai/2c65fdc3090e9011e9881660315065125",
        "transaction_id": "1645895596175",
      }
    ],
     "isError" : False
}

Create a direct payment link.

Parameter Type Required Default Description
customer Object required      - The customer object which contains (first name, last name, mobile number, email).
first_name String required      - The first name of the customer (included in customer object).
last_name String required      - The last name of the customer (included in customer object).
mobile_number Numeric required      - The mobile number of the customer (included in customer object).
email String optional      - The email of the customer (included in customer object).
directPayment Object required      - The direct payment object.
comments String optional      - The comments of the merchant in the checkout (included in directPayment object).
description String optional      - The description of the products which will customer buy (included in directPayment object).
expiryDate Date required      - The expiry date of payment link (included in directPayment object).
name String optional      - The name of the product which customer will buy (included in directPayment object).
shippingPolicyFlag Boolean optional      - This option helps merchant to add shipping policy section in checkout ( 1/0 - enable/disable) (included in directPayment object).
refundPolicyFlag Boolean optional      - This option helps merchant to add refund policy section in checkout ( 1/0 - enable/disable) (included in directPayment object).
shippingPolicyDetails String optional      - This is the shipping policy details (will exist if shippingPolicyFlag is 1) (included in directPayment object).
refundPolicyDetails String optional      - This is the refund policy details (will exist if refundPolicyFlag is 1) (included in directPayment object).
value Float required      - The price of the product(s) that customer will buy (included in directPayment object).
payment_gateway_id String required      - The payment gateway unique identifier.
payment_method_id String required      - The payment method unique identifier.

Returns

Returns a payment link url and transacion id, otherwise it returns an error.

Errors

Error code is a numeric or alphanumeric code that helps you to determine the nature of an error and why it occurred. The CirclePay API uses the following error codes:

General

Error Code Error Text Error Message
1110 Data missing {ATTRIBUTE} is missing.
1111 Invalid request structure The object structure sent is invalid. If you follow the documentation and still facing the same issue, please contact the support team.
1112 Invalid request data The {ATTRIBUTE} has invalid value.
1114 Field length error The field {ATTRIBUTE} length must be less than {ATTRIBUTE} and more than {ATTRIBUTE}.
1115 Invalid date format The date format is invalid. Please refer to the documentation for the right date format.
1116 Invalid email The email format is invalid.
1117 Invalid phone number format The phone number format is invalid (International format is required).

Authentication

Error Code Error Text Error Message
2110 Merchant key is incorrect The merchant key might be incorrect or doesn't exist.
2111 Invalid verification code The provided verification code is incorrect.
2112 Password is invalid The provided password isn't following the password requirements.
2113 Password isnot matching The password entered is not matching the first password field.

Customer

Error Code Error Text Error Message
3110 Cannot find the customer The customer phone number might be incorrect or doesn't exist.
3111 Customer already exist Another customer exists with the same phone number.
Error Code Error Text Error Message
4101 Cannot create Payment link Cannot create a payment link for an unknown reason. Please contact CirclePay support team.
4111 Cannot find the payment link The Payment link URL might be incorrect or doesn't exist.
4112 Expire date cannot be in the past Cannot add a past date for a payment link {ATTRIBUTE}.
4115 Payment link is expired Cannot pay an expired payment link.
4211 Cannot find form The form id might be incorrect or doesn't exist.
4212 Cannot update the form Cannot update the form as it might include responses.
4311 Cannot find coupon The coupon code might be incorrect or doesn't exist.
4312 Cannot update the coupon Cannot update the coupon as it might be linked to payments.
4313 Cannot delete the coupon Cannot delete the coupon as it might be linked to payments.

Invoices

Error Code Error Text Error Message
5101 Cannot create an invoice Cannot create an invoice for an unknown reason. Please contact CirlepPay support team.
5111 Cannot find the invoice The invoice number might be incorrect or doesn't exist.
5112 Cannot create the invoice Cannot add a past date for an invoice {ATTRIBUTE}.
5113 Cannot delete the invoice Cannot delete the invoice as it might be linked to other fields.
5114 Customer phone number is incorrect Cannot change the customer phone attached to the invoice.

Payment gateways

Error Code Error Text Error Message
7110 Cannot enable the payment gateway Cannot enable the payment gate for an unknow reason. Please contact CirclePay support team.
7111 Cannot find the payment gateway The payment gateway ID might be incorrect or doesn't exist.
7112 Cannot enable the payment method Cannot enable the payment method for an unknow reason. Please contact CirclePay support team.
7113 Cannot find the payment method The payment method ID might be incorrect or doesn't exist.
7114 Cannot set the payment method fee Cannot set the payment method fee. Please contact the support team.

Merchant

Error Code Error Text Error Message
8110 Cannot create a merchant The merchant phone number is being used by another account.
8111 Cannot find the merchant The merchant key might be incorrect or doesn't exist.
8112 Config file has incorrect structure The config JSON file structure is incorrect.
8113 Cannot send OTP The service failed to send an OTP to the merchant.
8114 Invalid Callback URL Callback URL structure is invalid.
8115 Merchant account is inactive Cannot do this operation as the account is inactive.
8116 Cannot update the merchant phone number Cannot update the merchant phone number as it's being used by another account.

Transactions

Error Code Error Text Error Message
9110 Transaction data request is missing The transaction data request is missing {ATTRIBUTE}.
9111 Cannot find the transaction The transaction ID might be incorrect or doesn't exist.
9112 Refund request rejected The payment gateway rejected the refund request for the following reason {ATTRIBUTE}.

Validation Rules

Validation rules verify that the data a user enters in a record meets the CirclePay standards.

Parmeter Type Validation Rule Error Message
Email Text Max length(chr) - 50 characters
Min length(chr) - NA
Must be a valid email format		 "The email must be less than 50 characters"
"The provided email isn't valid"
"The email is required"
shell