Payment gateways

Payment gateways is the first step to transform fiat money into a virtual currency, basically this service is to create a payment link using the following payment gateways

• Mono

• Pague a tiempo

• Payments way

• Pay now

• Zynle pay

• Orangepill payments

• M-Pesa

To start using one of them, you have to follow the following steps:

• Create an account on Orangepill

• Create a realm

• Get credentials for one of prior listed payment gateways

• Go to extension section on Orangepill dashboard

• Create a new Extension

Format of authentication object for each payment gateway

• Mono

{"api_key":"****", "base_url":"****"}

• Pague a tiempo

{"email":"****","password":"****","base_url":"****"}

• Payments way

{"base_url":"****","api_key":"****"}

• Pay now

{"base_url":"****","integration_id":"****","integration_key":"****"}

• Zynle pay

{"base_url":"****","merchant_id":"****","api_id":"****","api_key":"****"}

• Orangepill payments

{"base_url":"****","api_key":"****"}

• M-Pesa

{"shortCode": "****","passKey": "****","consumerKey": "****","consumerSecret": "****","baseUrl": "****"}

Usage

When you call payment gateways service you have to send two parameters

• payment_product: name of the payment gateway

  • mono

  • payOnTime

  • paymentsWay

  • payNow

  • zynlePay

  • orangepillPayments

  • mpesa

• payment_product_parameters: it varies according the payment gateway selected

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
    "payment_product": "mono",
    "payment_product_parameters": {
    }
}'

Mono

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
    "payment_product": "mono",
    "payment_product_parameters": {
        "account_id": "****",
        "amount": {
            "amount": 100,
            "currency": "COP"
        },
        "amount_validation": "free",
        "payer": {
            "document_number": "123456",
            "document_type": "CC",
            "email": "[email protected]",
            "name": "Angel",
            "phone": "[phone]"
        },
        "redirect_url": "https://example.com",
        "reference": {
            "editable": false,
            "required": false,
            "value": ""
        },
        "usage_type": "single_use"
    }
}'

Response

{
    "enabled": true,
    "id": "****",
    "link": "****",
    "reference": {
        "value": null,
        "required": false,
        "editable": false
    },
    "amount": {
        "currency": "COP",
        "amount": 100
    },
    "inserted_at": "2024-07-11T21:49:14.765544Z",
    "updated_at": "2024-07-11T21:49:14.765544Z",
    "external_id": null,
    "expires_at": null,
    "usage_type": "single_use",
    "account_id": "****",
    "redirect_url": "https://example.com",
    "payer": {
        "name": "Angel",
        "email": "[email protected]",
        "note": {
            "value": null,
            "required": false,
            "editable": false
        },
        "phone": "[phone]",
        "document_number": "123456",
        "document_type": "CC"
    },
    "successful_payments": 0,
    "amount_validation": "free"
}
```

Pague a tiempo

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data '{
    "payment_product": "payOnTime",
    "payment_product_parameters": {
        "itin": "123456",
        "reason": "primary",
        "description": "solid state",
        "invoice_number": "77",
        "currency_code": "COP",
        "value":"100",
        "tax_percentage": "1",
        "tax_value": "1"
    }
}'

Response

{
    "message": "Link de pago creado",
    "generated_link": "https://****/#/payment-link/****"
}

Payments way

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data '{
    "payment_product": "paymentsWay",
    "payment_product_parameters": {
        "amount": 1000.125,
        "description": "Description",
        "currency": "COP",
        "terminal_id": 123,
        "form_id": 123,
        "due_date": "2024/12/12",
        "redirection_url": "https://example.com",
        "services": [1,2]
    }
}'

Response

{
    "id": "e22441b1-52ad-4b28-8afe-1c3eb772ffdf",
    "amount": "1000.13",
    "status": null,
    "currency": "COP",
    "isQr": false,
    "description": "Description",
    "due_date": "2024-12-12",
    "link": "https://****/Link/****",
    "created_at": "2024-07-11T21:53:57.021Z",
    "updated_at": null,
    "deleted_at": null,
    "base_color": "#f11f40",
    "image_url": null,
    "redirect_link": "https://example.com",
    "short_link": "https://****/7us0vc",
    "expiration_time": "23:59"
}

Pay now (card)

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data '{
    "payment_product": "payNow",
    "payment_product_parameters": {
        "reference": "ullam",
        "amount": 9.96363,
        "additional_info": "sequi",
        "return_url": "http://norris.net",
        "result_url": "http://adonis.name",
        "type": "card"
    }
}'

Response

{
    "status": "Ok",
    "hash": "*****",
    "browser_url": "https://****/Payment/ConfirmPayment/18118406",
    "poll_url": "https://****/Interface/CheckPayment/?guid=****"
}

Pay now (mobile phone)

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data '{
    "payment_product": "payNow",
    "payment_product_parameters": {
        "reference": "ullam",
        "amount": 9.96363,
        "additional_info": "sequi",
        "return_url": "http://norris.net",
        "result_url": "http://adonis.name",
        "type": "mobilePhone",
        "phone": "0771111111",
        "method": "ecocash",
        "authemail": "[email protected]"
    }
}'

Response

{
    "status": "Ok",
    "instructions": "Dial *151*2*4# and enter your EcoCash PIN. Once you have authorized the payment via your handset, please click Check For Payment below to conclude this transaction",
    "hash": "84F780315C3EB0656B71344C0E09C854F5FE1EDCD8A05365E55525B58296FF4C691A1B1C7671C079AB9B517B199F64B5EC320A55C46C6C36E62DE4B23DE02C60",
    "poll_url": "https://www.paynow.co.zw/Interface/CheckPayment/?guid=f4510f3b-67d4-48c2-b553-37dd18272fc4",
    "reference": "18384491"
}

Zynle pay

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
    "payment_product": "zynlePay",
    "payment_product_parameters": {
        "reference_no": "1725489982",
        "amount": 1.11,
        "description": "test description",
        "first_name": "Angel",
        "last_name": "Barrancos",
        "address": "Blooming Avenue",
        "email": "[email protected]",
        "phone": "0774065514",
        "city": "Santa cruz",
        "state": "Santa cruz",
        "currency": "ZMW",
        "zip_code": "1234",
        "country": "Bolivia",
        "user_defined_1": "59179071059"
    }
}'

Response

{
    "response_code": "100",
    "response_description": "Redirect",
    "reference_no": "1725489976",
    "transaction_id": 9692741235,
    "redirect_url": "https://sandbox.zynlepay.com/redirect-url/1725489976",
    "amount": 1.11,
    "udf1": "Valid card transaction",
    "udf2": "",
    "udf3": "",
    "udf4": "",
    "udf5": "",
    "operator_reference": 2592584423
}

Orangepill payments

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data '{
    "payment_product": "orangepillPayments",
    "payment_product_parameters": {
        "merchant_reference": "111",
        "payment_profile": "5d47ee6f-883b-4f84-a982-71bcac19a8b1",
        "amount": 1000,
        "organisation": "0c39337f-b691-4b5b-ba90-88dc2b2771c9",
        "customer": "cf856cd2-224d-4ac1-a7f8-1ea47c874856",
        "details": {
            "change_amount": true,
            "change_amount_max": 1000,
            "change_amount_min": 100000
        },
        "redirect_url": "https://example.com/redirect",
        "valid_until": "2024-09-16T02:02:22Z",
        "webhook_transaction_update": "https://example.com/test"
    }
}'

Response

{
    "transaction": "",
    "customer": "cf856cd2-224d-4ac1-a7f8-1ea47c874856",
    "payment_profile": "5d47ee6f-883b-4f84-a982-71bcac19a8b1",
    "organisation": "0c39337f-b691-4b5b-ba90-88dc2b2771c9",
    "id": "74ac09f7-01ea-41be-8993-82076d49732c",
    "amount": 1000,
    "merchant_reference": "111",
    "payment_product": "",
    "status": "CREATED",
    "active": true,
    "redirect_url": "https://example.com/redirect",
    "webhook_transaction_update": "https://example.com/test",
    "details": {
        "change_amount": true,
        "change_amount_max": 1000,
        "change_amount_min": 100000,
    "redirect_url": "https://example.com/redirect",
        "approval_url": "https://sandbox-api.payments.orangepill.cloud/paymentlink/74ac09f7-01ea-41be-8993-82076d49732c"
    },
    "created_at": "2024-09-04T23:18:34+00:00",
    "updated_at": "2024-09-04T23:18:34+00:00",
    "valid_until": "2024-09-16T02:02:22+00:00"
}

M-Pesa

Request

curl --location 'https://api.orangepill.cloud/v1/payment-gateways/createPaymentLink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data '{
    "payment_product": "mpesa",
    "payment_product_parameters": {
        "transaction_type": "CustomerPayBillOnline",
        "amount": 1,
        "source": "254708374149",
        "phoneNumber": "254708374149",
        "resultUrl": "https://example/result",
        "reference": "reference",
        "description": "description"
    }
}'

Response

{
    "merchant_request_id": "b63c-4f5b-830c-97562f598bca31994",
    "checkout_request_id": "ws_CO_26112024072108728708374149",
    "response_code": "0",
    "response_description": "Success. Request accepted for processing",
    "customer_message": "Success. Request accepted for processing"
}

Once you get the response, you should use link provided by each payment gateways and it will display a form to make the payment using different financial instruments such as credit card, debit card, PSE and so on.

Some payment gateways does not return a link because they use mobile money, such as follow:

• Pay Now (it has both, payment link and mobile money)

• M-Pesa

For mobile money the customer will get a USSD code to accept or reject the transfer

After you initiate the payment, the payment gateway will invoke a wallet agent which is in charge of emitting virtual currency but that process will be covered on another section.