Navbar MENU

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.

Requirements

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

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

Transaction Process

Step 1. You make API request to get payment URI and ID.
Step 2. You redirect your client to URI that was provided in response of API call.
Step 3. Client makes a payment on our side, and after success (failed) client is redirected back to URI that was provided by you.
Step 4. To get charge status you make another API call to get charge details. In the case if you provided webhook URI, we will automatically push charge 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_token for each shop. You can use it for Bearer auth or by including additional parameter api_token to the request. (RFC: 6750)

Any request may include headers:
"Content-Type: application/json"
"Accept: application/json"

Authentication

Authenticate your identity when using the API calls by including your secret token in the request. Your token carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas.

To authenticate via bearer auth, use: -H "Authorization: Bearer verySecretApiToken"

Charges

Initialization

POST /api/charges

Example request content:

{
   "amount" : "10.00",
   "currency" : "USD",
   "pay_method" : "card",
   "description" : "Test description",
   "email" : "client@domain.ltd"
}

Request fields

Field Description Validation
amount required Positive float value representing how much to charge. e.g.: 500 Min: 1.00;
Max: 10000.00 (or depends on your plan)
reference_id optional Unique transaction ID. If your account already has charge with such reference id, then request will be rejected. e.g.: id:000001 Min: 4;
Max: 255 characters
currency required Charge currency e.g.: USD, EUR, GBP, RUB,BTC. Must be a supported currency for mechant. ISO 4217
3-character code
pay_method required Payment metod e.g.: card,bitcoin card, webmoney, qiwi,bitcoin. Must be a supported payment method for merchant.
description required 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. e.g.: Charge #00001 Min: 4 chars
Max: 255 chars
email required Payer email. e.g.: client@domain.ltd RFC 2821

In case when you use bitcoin payment method and currency BTC, amount must be presented in satoshi.
If you provide not BTC in the currency field, amount will be recalculated depending on the currency, that you provided in the transaction initialization request. Anyway in the response you will get currency BTC and amount in satoshi.

Field Description Validation
return_success_url optional URI where end client will be returned after successful transaction. URI RFC 3986
return_error_url optional URI where end client will be returned if he cancels transaction or if error will occur. URI RFC 3986
callback_url optional URI where our server can send POST request with transaction details after client payment. URI RFC 3986

Example response content:

{
  "data": {
      "charge": {
          "type": "charge",
          "id": "d8eb4580-f858-11e6-8fb6-47e9e29fb94c",
          "attributes": {
              "livemode": true,
              "status": "initialized",
              "amount": "10.00",
              "fee": null,
              "rolling": null,
              "total_amount": null,
              "currency": "USD",
              "pay_method": "card",
              "description": "Test description",
              "ip_address": null,
              "email": "client@domain.ltd",
              "source": null,
              "failure": null,
              "reference_id": null,
              "created_at": 1487697116,
              "updated_at": 1487697116,
              "valid_till": 1487697716
          }
      },
      "links": {
          "redirect_url": 
  "https://domain.ltd/order/card/d8eb4580-f858-11e6-8fb6-47e9e29fb94c"
      }
  },
  "meta": {
      "server_time": 1487697116,
      "server_timezone": "UTC",
      "api_version": "v2"
  }
}

Response fields

Field Description
id Unique identificator for the object.
livemode Indicating whether the object created in live mode or test mode.
status The status of the payment is either initialized, successful, authentication, pending, failed.
amount A positive float value representing how much to charge.
fee Null or a positive float value representing system payment fee.
rolling Null or a positive float value representing rolling amount of the charge.
total_amount Null or a positive float value representing net amount of the charge.
currency Three-letter ISO currency code.
pay_method Payment method is either card, webmoney, qiwi, etc.
description Description, that payer will see on the payment form.
ip_address ipv4 of the payer.
source An object, null or contains parameters for a specific payment method.
failure An object, null or contains parameters failure_code, failure_message.
reference_id Unique identificator for the object provided by the merchant’s request.
created_at Time (measures in seconds since Unix epoch) at which charge was initialized.
updated_at Time at which charge was updated (status changed, refund, etc.).
valid_till Time at which charge status will be automatically changed to failed.
redirect_url Containing link related to the payment form.

Retrieve charge details

GET /api/charges/{charge_id}

Description

Field Description Validation
{charge_id} Unique identificator for the charge. UUID

Example response content:

{ "data": { "charge": { "type": "charge", "id": "1499ae90-f860-11e6-a8b6-e74ae337c2e8", "attributes": { "livemode": true, "status": "successful", "amount": "1.00", "fee": "0.01", "rolling": "0.05", "total_amount ": "0.94", "currency": "USD", "pay_method": "card", "description": "test", "source": { "email": "client@domain.ltd", "ip_address": "192.168.0.1", "name": "John Doe", "card_number": "4111********1111" }, "failure": null, "reference_id": null, "created_at": 1487700222, "updated_at": 1487700251, "valid_till": 1487700822 } } }, "meta": { "server_time": 1487761883, "server_timezone": "UTC", "api_version": "v2" } }
{ "data": { "charge": { "type": "charge", "id": "ac7eaa60-f85f-11e6-bce1-93ceeb4f7e49", "attributes": { "livemode": true, "status": "failed", "amount": "1.00", "fee": null, "rolling": null, "currency": "USD", "pay_method": "card", "description": "Test description", "source": { "email": "client@domain.ltd", "ip_address": "192.168.0.1", "name": "John Doe", "card_number": "4111********1111" }, "failure": { "code": "processing_failed", "message": "Authentication failed" }, "reference_id": null, "created_at": 1487700048, "updated_at": 1487700070, "valid_till": 1487700648 } } }, "meta": { "server_time": 1487761518, "server_timezone": "UTC", "api_version": "v2" } }

Widget

You need to make next steps for placing payment form on your website:

Step 1. Initialize transaction with POST /api/charges method.
Step 2. Call method /api/charges/{charge_id}/widget, where {charge_id} is the unique charge identifier from first step. You need to place HTML code of form, which you get in response, on your website. After payment processing you will get notification with transaction details on CallbackURL, given by you, and payer will be re-directed on the scenario address given by you (SuccessURL, FailureURL) through GET method with additional parameter payment_id={charge_id}.
Step 3. Call GET method GET /api/charges/{charge_details} for receiving and confirmation of payment details.

Also you can create your own form with parameters from object "constructor".
You should send the form with method from parameter action by link from parameter action_uri.

Here is a list of required attributes in the customized form:

Other parameters from response are optional and informational for payer.

Transfers

Transfer to card

POST /api/transfers/card

Example request content:

{
    "amount" : "10.00",
    "currency" : "USD",
    "description" : "Test description",
    "name" : "John Doe",
    "card_number" : "4111111111111111",
    "card_expiry_month" : "02",
    "card_expiry_year" : "19",
    "address_country" : "US",
    "address_city" : "New York",
    "address_line1" : "123 East 169th Street Apt. 2A Bronx, NY 10456"
}

Request fields

Field Description Validation
amount required Positive float value representing how much to charge. e.g.: 500 Min: 1.00;
Max: 10000.00 (or depends on your plan)
currency required Card currency. e.g.: USD Min: 4 chars
Max: 255 chars
description optional Description of transaction that will be displayed in the web interface alongside the transfer. e.g.: Transfer #123 Min: 5 chars
Max: 255 chars
name required Real credit card owner name. e.g.: Johm Smith Min: 2 chars
Max: 64 chars
card_number required Recipient’s card number. e.g.: 4111111111111111 /^[0-9]+$/
card_expiry_month required Real expiry month of credit card. e.g.: 01 MM
card_expiry_year required Real expiry year of credit card. e.g.: 19 YY
address_country required Cardholder country. e.g.: UK ISO 3166-1 alpha-2
address_city required Cardholder city. e.g.: London Min: 10 chars
Max: 255 chars
address_line1 required Cardholder address. e.g.: 483 West St. Vista, CA 92083 Min: 10
Max: 255 chars

Example response content:

{ "data": { "transfer": { "type": "transfer", "id": "34004470-fffb-11e6-b975-1fdcb0cb124d", "attributes": { "livemode": true, "status": "pending", "amount": "10.00", "fee": "4.40", "total_amount": "14.40", "currency": "USD", "description": "Test description", "destination": { "name": "John Doe", "card_number": "4111********1111" }, "failure": null, "created_at": 1488536505, "updated_at": 1488536505 }, "relationships": { "wallet": { "type": "wallet", "attributes": { "name": "Card (US Dollar)", "currency": "USD" } } } } }, "meta": { "server_time": 1488536505, "server_timezone": "UTC", "api_version": "v2" } }
{ "type": "error", "code": "invalid_request_error", "errors": [ "Not sufficient funds." ], "meta": { "server_time": 1488531153, "server_timezone": "UTC", "api_version": "v2" } }

Retrieve transfer details

GET /api/transfers/{transfer_id}

Example response content (successful):

{
    "data": {
        "transfer": {
            "type": "transfer",
            "id": "34004470-fffb-11e6-b975-1fdcb0cb124d",
            "attributes": {
                "livemode": true,
                "status": "successful",
                "amount": "10.00",
                "fee": "4.40",
                "total_amount": "14.40",
                "currency": "USD",
                "description": "Test description",
                "destination": {
                    "name": "John Doe",
                    "card_number": "4111********1111"
                },
                "failure": null,
                "created_at": 1488536505,
                "updated_at": 1488536505
            },
            "relationships": {
                "wallet": {
                    "type": "wallet",
                    "attributes": {
                        "name": "Card (US Dollar)",
                        "currency": "USD"
                    }
                }
            }
        }
    },
    "meta": {
        "server_time": 1488537213,
        "server_timezone": "UTC",
        "api_version": "v2"
    }
}

Refunds

Create refund request

POST /api/refunds

Example request content:

{
    "charge_id" : "1499ae90-f860-11e6-a8b6-e74ae337c2e8",
    "amount" : "1.00"
}

Request fields

Field Description Validation
amount required Positive float value representing how much to charge. e.g.: 500 Min: 1.00;
Max: 10000.00 (or depends on your plan)
charge_id required Refundable transaction id. e.g.: 1499ae90-f860-11e6-a8b6-e74ae337c2e8 UUID

Example response content:

{ "data": { "charge": { "type": "charge", "id": "1499ae90-f860-11e6-a8b6-e74ae337c2e8", "attributes": { "livemode": true, "status": "successful", "amount": "1.00", "currency": "USD", "pay_method": "card", "description": "payment", "source": { "email": "client@domain.ltd", "ip_address": "192.168.0.1", "name": "John Doe", "card_number": "4111********1111" }, "failure": null, "reference_id": null, "created_at": 1487700222, "updated_at": 1487700251, "valid_till": 1487700822 }, "included": [{ "type": "refund", "id": "9b4a4910-0a5d-11e7-a2d9-955600df3a84", "attributes": { "amount": "1.00", "description": null, "created_at": 1489678281, "updated_at": 1489678281 } }] } }, "meta": { "server_time": 1489678281, "server_timezone": "UTC", "api_version": "v2" } }
{ "type": "error", "code": "method_error", "errors": "Refundable charge not found.", "meta": { "server_time": 1489678103, "server_timezone": "UTC", "api_version": "v2" } }

Webhooks

Example of callback object that will be sent:

{
    "webhook": {
        "type": "charge.succeeded"
    },
    "data": {
        "charge": {
            "type": "charge",
            "id": "7b42e4a0-f8ed-11e6-ab60-b981d1c5d76f",
            "attributes": {
                "livemode": true,
                "status": "successful",
                "amount": "10.00",
                "currency": "USD",
                "pay_method": "card",
                "description": "Test description",
                "source": {
                    "email": "client@domain.ltd",
                    "ip_address": "192.168.0.1",
                    "name": "John Doe",
                    "card_number": "4111********1111"
                },
                "failure": null,
                "reference_id": null,
                "created_at": 1487760954,
                "updated_at": 1487760954,
                "valid_till": 1487761554
            }
        }
    },
    "meta": {
        "server_time": 1487761027,
        "server_timezone": "UTC",
        "api_version": "v2"
    }
}

Types of events

Event Description
charge.succeeded Occurs whenever a successful charge attempts.
charge.failed Occurs whenever a failed charge attempts.
transfer.succeeded Occurs whenever a transfer become successful.
transfer.failed Occurs whenever a transfer become failed and funds returned to wallet.

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.

Code Meaning
2xx If the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.
4xx 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.
5xx 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.