API Documentation Page

|

Getting Started

Welcome

Welcome to the OrangePay API documentation. The OrangePay API allows you to initialize and process credit throught OrangePay gateway in a simple, programmatic way using convetional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

Requirments

To create shop account and start receiving payments, the following data must be provided to OrangePay

Item Description
Server IP list Your server(s) IP(s) that will be added to our firewall.
Shop URL Your actual shop URL
Return Success URL URL where end client will be returned after successful transaction
Return Error URL URL where end client will be returned if he cancels transaction or if error will occour
Callback URL Optional url where our server can send POST request with transaction details after transaction

Transaction Process

Step 1.
You make Server - to - Server POST request to get payment URL and transaction ID.
Step 2.
You redirect your client to URL that was provided in response of Server - to - Server POST.
Step 3.
Client makes a payment on our side, and after success he is redirected back to URL that was provided by you.
Step 4.
To get transaction status you make another Server - to Server GET request to get transaction details.

Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required. After shop registration you will be given api_key and password_key for each shop. These items are used for Basic HTTP auth.

Remember to keep api_key and password_key in secret!

Transaction initialisation

Server - to - Server POST request is sent to:

 https://[api_key]:[password_key]@pay.payorange-pay.com/index.php/api/v1/widget/transactions

cURL example request:

 curl https://pay.payorange-pay.com/index.php/api/v1/widget/transactions \
                  -u [API_KEY]:[PASSWORD_KEY] \
                  -d reference_id=400 \
                  -d amount=400 \
                  -d currency=USD \
                  -d client_ip=192.168.0.1 \
                  -d email=client@domain.ltd \
                  -d description=Example credit card charge \
                  -d pay_method=card
              
Field* Description Validation
reference_id* Unique transaction ID. If OrangePay system already has record with such transaction id, then transaction will be rejected Min: 4;
Max: 255 chars
amount* Positive integer in minor currency units. ( e.g. specify 100 cents if you want to charge $1.00 ). Only numbers without decimals are accepted. Minimal charge unit is 100 ( 1.00 ) of each currency. Min: 100; Max: 100000, (1000000 for RUB)
currency* Transaction currency, ISO 4217 3-character code ( example: USD, EUR, RUB ) 3 chars
client_ip* IP address of an actual client. IPv4
email* Payer email. Can be used to send receipts RFC 2821
description* Description of transaction that will be displayed in the web interface alongside the charge. Note that if you use OragenPay to send automatic email receipts to your customers, your receipt emails will include the description of the charge that they are describing. Min: 4; Max: 255 chars
pay_method Optional parameter to bypass first OrangePay widget form step.

To bypass first step of widget form pay_method POST param can be sent to your API server. pay_method available values are: card, webmoney, paypal, qiwi, yandex

** All fields are required *

Example Request object with all mandatory data params:

{
    "reference_id": "tr_15rpgM2eZvKYlo2C1lUyzOhy",
    "amount": "1000" // 10.00
    "currency": "EUR",
    "client_ip": "192.168.0.1",
    "email": "client@domain.ltd",
    "description": "Example credit card charge"
}

(Optional) Example Request to bypass first step of payment widget form:

{
    "reference_id": "tr_15rpgM2eZvKYlo2C1lUyzOhy",
    "amount": "1000" // 10.00
    "currency": "USD",
    "client_ip": "192.168.0.1",
    "email": "client@domain.ltd",
    "description": "Example webmoney charge",
    "pay_method": "webmoney"
}

Example Response:

{
    "status": "success",
    "message": "Successfully initialized transaction.",
    "data": {
        "redirect_url": "https://pay.payorange-pay.com/index.php/widget/wch_XXXXXXXXXXXXXXXXXXXX",
        "transaction": {
            "id": "wch_XXXXXXXXXXXXXXXXXX",
            "reference_id": "4244345566",
            "livemode": false,
            "status_id": "INITIALIZED",
            "paid": false,
            "amount": 1000,
            "amount_readable": "10.00",
            "currency_id": "EUR",
            "description": "Example credit card charge",
            "ip_address": "192.168.0.1",
            "email": "client@domain.ltd",
            "source": null,
            "failure_code": null,
            "failure_message": null,
            "created_at": 1431688005,
            "updated_at": 1431688005,
            "valid_till": 1431688605
        }
    },
    "status_code": 201,
    "@meta": {
        "server_time": 1431688005,
        "server_timezone": "Europe/Riga",
        "api_version": "v1"
    }
}

Client redirection

After you get successful response. Redirect client to URL that is specified in "redirect_url".

Remember that Redirection link is valid 600 seconds (10 minutes). created_at field in our response indicates transaction initialisation time.

Client return

After client paid transaction OrangePay will redirect client to return_url that you specified with shop registration. OrangePay attaches query param transaction_id that is unique for each transaction. transaction_id can be found in OrangePay response.

Example:

 http://your-shop.com/return/success/?transaction_id=ch_vB9RO37N1aM7ZOdWmpnyxXXX

Retrieve transaction details

To retrieve the details of transaction that has previously been created supply the unique transaction_id that was returned from OrangePay response and OrangePay will return the corresponding transaction information.

Argument Description
transaction_id The identifier of the transaction to be retrieved.

Example cURL request:

 curl https://pay.payorange-pay.com/index.php/api/v1/widget/transactions/[TRANSACTION_ID] \
    -u [API_KEY]:[PASSWORD_KEY]

Example:

 curl https://pay.payorange-pay.com/index.php/api/v1/widget/transactions/wch_vB9RO37N1aM7ZOdWmpnyxXXX \
    -u 715c12c43a3fcc2fd46468028dfa1f5f:380d370437291a7c0bb88b0fffbf4be7

Example Response:

 {
    "status": "success",
    "data": {
        "transaction": {
            "id": "wch_vB9RO37N1aM7ZOdWmpnyxXXX",
            "reference_id": "tr_15rpgM2eZvKYlo2C1lUyzOhy",
            "livemode": false,
            "status_id": "SUCCESSFUL",
            "paid": true,
            "amount": 200,
            "amount_readable": "2.00",
            "currency_id": "USD",
            "description": "Example credit card charge",
            "ip_address": "192.168.0.1",
            "email": "client@domain.ltd",
            "source": {
                ...
            },
            "failure_code": null,
            "failure_message": null,
            "created_at": 1431688005,
            "updated_at": 1431688005,
            "valid_till": 1431688605
        }
    },
    "status_code": 201,
    "@meta": {
        "server_time": 1431688005,
        "server_timezone": "Europe/Riga",
        "api_version": "v1"
    }
}

In case if payment was made with card source array will be in format of:

Example with WebMoney:

 "source": {
    "object": "webmoney",
    "wm_id": "475842040000",
    "wm_purse": "E131206450000",
    "wm_country_id": "GB",
}

Response Object Explanation:

Argument Description
id Unique transaction id
reference_id Unique id sent from client side
livemode Boolean, indicates testing / production mode
status_id Status of transaction. Can be INITIALIZED, PENDING, SUCCESSFUL, FAILED
paid Boolean. Indicates if transaction was paid
amount Positive integer. Amount charged in minor units
amount_readable Amount charged in readable format
currency_id Three-letter ISO currency code representing the currency in which the charge was made

Remember that Redirection link is valid 600 seconds ( 10 minutes ). created_at field in our response indicates transaction initialisation time.

Retrieve shops balance

You can retrieve shop balance by GET request

Example cURL request:

 curl https://pay.payorange-pay.com/index.php/api/v1/balance \
                  -u [API_KEY]:[PASSWORD_KEY]
              

Example:

 curl https://pay.payorange-pay.com/index.php/api/v1/balance \
                  -u 715c12c43a3fcc2fd46468028dfa1f5f:380d370437291a7c0bb88b0fffbf4be7
              

Response example:

 {
    "status": "success",
    "message": "Account balance.",
    "data": {
        "balance": [
            {
                "type_id": "card",
                "currency_id": "USD",
                "balance": "0.00",
                "pending": "0.00"
            },
            {
                "type_id": "paypal",
                "currency_id": "EUR",
                "balance": "0.00",
                "pending": "0.00"
            },
            {
                "type_id": "qiwi",
                "currency_id": "RUB",
                "balance": "0.00",
                "pending": "0.00"
            },
            {
                "type_id": "webmoney",
                "currency_id": "USD",
                "balance": "0.00",
                "pending": "0.00"
            },
            {
                "type_id": "webmoney",
                "currency_id": "RUB",
                "balance": "0.00",
                "pending": "0.00"
            },
            {
                "type_id": "yandex",
                "currency_id": "RUB",
                "balance": "0.00",
                "pending": "0.00"
            }
        ]
    },
    "status_code": 201,
    "@meta": {
        "server_time": 1466278861,
        "server_timezone": "Europe/Riga",
        "api_version": "v1"
    }
}

Transfer request

To make transfer request you will need parameters:

Field* Description Validation
currency* Unique transaction ID. If OrangePay system already has record with such transaction id, then transaction will be rejected Min: 4; Max: 255 chars
cc_currency Real credit's card currency. Supports USD, EUR, RUB
amount* Positive float in currency units. ( e.g. specify 2.15 if you want to charge $2.15 ). Min: 1; Max: 100000 (may vary depending on currency or payment system)
destination* Recipient's wallet number on transferrable payment system Credit card: /^[0-9]+$/
WebMoney: /^[rZ|rE|rU|rR][\d]{12}$/
YandexMoney: /^\d{11,15}$/
Qiwi: /^\d+$/
description* Description of transaction that will be displayed in the web interface alongside the transfer. Min: 5; Max: 255 chars
nameOnCard Uses when request Credit Card transfer. Real credit card owner name. Min: 10; Max: 255 chars
expiry Uses when request Credit Card transfer. Real expiry date of credit card. Example: "01/20"
address Uses when request Credit Card transfer. Cardholder address Example: "483 West St. Vista, CA 92083"; Min: 10; Max: 255 chars

Credit card transfer example request:

 curl https://pay.payorange-pay.com/index.php/api/v1/transfers/card \
    -u 715c12c43a3fcc2fd46468028dfa1f5f:380d370437291a7c0bb88b0fffbf4be7 \
    -d currency="USD" \
    -d cc_currency="EUR" \
    -d amount=5 \ // (5 USD)
    -d destination="4111111111111111" \
    -d nameOnCard="Ivan Ivanov" \
    -d expiry="01/20"
    -d description="Example Card transfer request"

WebMoney transfer example request:

 curl https://pay.payorange-pay.com/index.php/api/v1/transfers/wm \
    -u 715c12c43a3fcc2fd46468028dfa1f5f:380d370437291a7c0bb88b0fffbf4be7 \
    -d currency="USD" \
    -d amount=5 \ // (5 USD)
    -d destination="Z111111111111" \
    -d description="Example WebMoney transfer request"

YandexMoney transfer example request:

 curl https://pay.payorange-pay.com/index.php/api/v1/transfers/yandex_money \
    -u 715c12c43a3fcc2fd46468028dfa1f5f:380d370437291a7c0bb88b0fffbf4be7 \
    -d currency="RUB" \
    -d amount=5 \ // (5 RUB)
    -d destination="41001XXXXXXXXXX" \
    -d description="Example YandexMoney transfer request"

Qiwi transfer example request:

 curl https://pay.payorange-pay.com/index.php/api/v1/transfers/qiwi \
    -u 715c12c43a3fcc2fd46468028dfa1f5f:380d370437291a7c0bb88b0fffbf4be7 \
    -d currency="RUB" \
    -d amount=5 \ // (5 RUB)
    -d destination="79151112233" \
    -d description="Example Qiwi transfer request"

Credit card example response:

 {
    "status": "success",
    "message": "Successfully transferred money.",
    "data": {
        "transfer": {
            "id": "transfer_XM6o79e4xZadXXXXXX",
            "destination": "4111111111111111",
            "description": "Example Card transfer request",
            "amount": X.XX,
            "fee": X.XX,
            "total_transferred": 1,
            "currency_id": "USD",
            "status": "PENDING",
            "created_at": {
                "timestamp": 14665691000,
                "date_time": "10-01-2016 00:00:00"
            }
        }
    },
    "status_code": 201,
    "@meta": {
        "server_time": 14665691000,
        "server_timezone": "Europe/Riga",
        "api_version": "v1"
    }
}

UI language

OrangePay supports multilingual user interface. To make request you will need to add language parameter in Transaction initialisation, that can take en, ru values. If you need another language set, please contact our support.

Callbacks

At the moment OrangePay supports two types of callbacks. If callback url was provided, then OrangePay after transaction success or failure will send POST request, that will contain JSON data, to provided callback URL.

Callback types:

  • transaction.succeeded
  • transaction.failed

Example of callback object that will be sent:

{
    "event": "transaction.succeeded",
    "data": {
        "transaction": {
            "id": "wch_vB9RO37N1aM7ZOdWmpnyxXXX",
            "reference_id": "tr_15rpgM2eZvKYlo2C1lUyzOhy",
            "livemode": false,
            "status_id": "SUCCESSFUL",
            "paid": true,
            "amount": 200,
            "amount_readable": "2.00",
            "currency_id": "USD",
            "description": "Example credit card charge",
            "ip_address": "192.168.0.1",
            "email": "domain.ltd@gmail.com",
            "source": {
                ...
            },
            "failure_code": null,
            "failure_message": null,
            "created_at": 1431688005,
            "updated_at": 1431688005,
            "valid_till": 1431688605
        }
    },
    "status_code": 200,
}

API Response Codes

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.