{
  "Rates": [
    {      
       "Currency": "ZMW",
       "Rate": 13.059026
    },
    {    "Currency": "ZAR",
         "Rate": 15.326697
    },
  ]
}

📘

Note

The rate indication is only used to approximate the converted prices based on current market rates. When the transaction goes through, the foreign exchange rate used to settle the transaction may be slightly different than the indication rate returned in getRates depending on market fluctuations.

{
  "RateOffers": [
     {      
        "Currency": "EUR",
        "Id": "e3ac01e4-f48b-4f38-ba31-cd2bf51d61ba",
        "Expiry": "2016-10-03T18:04:21.830514Z",
        "Rate": 0.9349
     },
     {      
        "Currency": "CAD",
        "Id": "8ca2b5a3-8120-4238-88ff-8811223aaef8",
        "Expiry": "2016-10-03T18:04:21.524409Z",
        "Rate": 1.3842
     }
  ]
}

📘

Saving Rate Offers

Rate offers typically expire 24 hours after they have been created with longer expiry times available in special circumstances. We recommend that getRates be called a couple of times per day for a better user experience which means it's possible to have multiple, non-expired rate offers. In that case, the latest rate offer should be used for new visitors.

You will send an HTTP POST request to the Session API to create a Session. To enable Auto Capture, set the AutoCapture boolean to true. It can be verified with the AutoCapture field in the response, which should also be set to true. See the Reach Session API Reference for a more detailed look at the API.

    # Location
    POST https://api.withreach.com/v1/session
    
    #Headers
    Authorization: Basic YWNjb3VudDpzZWNyZXQ=
    Content-Type: application/json
    
    #Body
    {
        "MerchantReference": "unique_reference_provided_by_merchant",
        "Currency": "USD",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.00,
                "Quantity": 1
            },
            {
                "Name": "Item 2",
                "Amount": 12.00,
                "Quantity": 2
            }
        ],
        "BillingProfile": {
            "Name": "First Last",
            "Email": "[email protected]",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "X0X0X0",
                "Phone": "4031234567"
            }
        },
        "ShippingDetails": {
            "ShippingAmount": 0.00,
            "DutyAmount": 0.00,
            "Name": "First Last",
            "Email": "[email protected]",
            "Phone": "4031231234",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "X0X0X0"
            }
        },
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
    }

    #Headers
    Content-Type: application/json
    
    #Body
    {
        "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
        "State": "CREATED",
        "MerchantReference": "unique_reference_provided_by_merchant",
        "Items": [
            {
                "Name": "Item 1",
                "Amount": 10.00,
                "Quantity": 1
            },
            {
                "Name": "Item 2",
                "Amount": 12.00,
                "Quantity": 2
            }
        ],
        "Currency": "USD",
        "TotalAmount": 34.00,
        "BillingProfile": {
            "Name": "First Last",
            "Email": "[email protected]",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "X0X0X0",
                "Phone": "4031234567"
            }
        },
        "ShippingDetails": {
            "ShippingAmount": 0.00,
            "DutyAmount": 0.00,
            "Name": "First Last",
            "Email": "[email protected]",
            "Phone": "4031231234",
            "Address": {
                "Street": "123 Sreet",
                "City": "City",
                "Region": "AB",
                "Country": "CA",
                "Postcode": "X0X0X0"
            }
        },
        "AutoCapture": true,
        "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
        "CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
    }

Follow these steps to instantiate the Drop-In:

1. Add an HTML container element to your page to hold the Drop-In.
2. Create a JavaScript method to complete logic once the Drop-In is successful.
3. Create a JavaScript method to handle failure cases if payment is not successful.
4. Add the Drop-In (rch.js) script to your page.
5. Call the Reach init() method and pass in an object with a target, id, onSuccess, and onFailure property.

View the Drop-In Javascript Library (rch.js) Guide for more detailed information about the rch.js file.

When finished, your page should look something like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        ...
        ...
        <script defer src="https://asset.withreach.com/dist/rch.js" onload="init()"></script>
        <script>
            function onSuccess() {
                <!-- Perform any actions after the Drop-In is completed (i.e. redirect to success URL). -->
                window.location.replace("/success/");
            }
            function onFailure(error) {
                <!-- Perform any actions to handle payment failure. -->
                document.querySelector("#message").innerHTML = 
                    "Oops! Something went wrong. More information: " + error.errorCode + 
                    ", " + error.errorMessage + " Please review your information.";
            }
            function init() {
                <!-- 91b64778-0d37-479c-ae9f-32f6685ac6ea is the session ID -->
                RCH_CC.rchInit({target:"#rch-dropin",id:"91b64778-0d37-479c-ae9f-32f6685ac6ea", onSuccess, onFailure});
            }
        </script>
        ...
        ...
    </head>
    <body>
        ...
        ...
        <div id=”rch-dropin”></div>
        ...
        ...
    </body>
</html>

The onSuccess method passed into the init method indicates that the payment was successfully initiated, and you can now redirect the shopper to the success page.

📘

NOTE

The onSuccess method does not indicate that the payment was completed only that the payment process has been successfully initiated. The payment is not complete until you’ve receive the ORDER_PROCESSED notification.

The onFailure method passed into the init method is called when an error that is unrecoverable inside the session is encountered. The error code and message will be passed into onFailure and can be used to determine which action to take. For example, a message could be displayed to the end user indicating what failed.

The Drop-In will notify you when it takes action against a Session or Order. To receive these notifications, you must configure your server to listen for them by creating an endpoint at the webhook URL provided to Reach during onboarding. See the Notifications Guide for more details.

If the Order is processed successfully, you will receive the SESSION_COMPLETED, ORDER_AUTHORIZED, and ORDER_PROCESSED notifications. Once you’ve received the ORDER_PROCESSED notification the payment is considered complete.

📘

NOTE

In the case of auto capture, the SESSION_COMPLETED and ORDER_AUTHORIZED notifications should be logged but not actioned on.

The ORDER_PROCESSED notification will look like this:

{
  "EventType": "ORDER_PROCESSED",
  "Order": {
    "OrderId": "cc7236aa-d11b-436c-a29c-d26cecadc847",
    "State": "PROCESSED",
    "MerchantReference": "unique_reference_provided_by_merchant",
    "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea"
  }
}

Upon successfully receiving a notification, you should respond with HTTP status 200. If you reply with a status outside that range, we will resend the notification later. See the Notifications Guide for more details.

To instantiate the most basic version of the Reach Drop-In, follow these steps:

1. Add an HTML container element to your page to hold the Drop-In
2. Create a JavaScript method to complete logic once the Drop-In is successful
3. Create a JavaScript method to handle failure cases if payment is not successful
4. Add “Reach Drop-In” (rch.js) script to your page
5. Call the Reach init() method and pass in an object with a target, id and onSuccess property.

View the Drop-In Javascript Library (rch.js) Guide for more detailed information about the rch.js.

When complete, your page should look something like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        ...
        ...
        <script defer src="https://asset.withreach.com/dist/rch.js" onload="init()"></script>
        <script>
            function onSuccess() {
                <!-- Perform any actions after the Drop-In is completed (i.e. redirect to success URL). -->
                window.location.replace("/success/");
            }
            function onFailure(error) {
                <!-- Perform any actions to handle payment failure. -->
                document.querySelector("#message").innerHTML = 
                    "Oops! Something went wrong. More information: " + error.errorCode + 
                    ", " + error.errorMessage + " Please review your information.";
            }
            function init() {
                <!-- 91b64778-0d37-479c-ae9f-32f6685ac6ea is the session ID -->
                RCH_CC.rchInit({target:"#rch-dropin",id:"91b64778-0d37-479c-ae9f-32f6685ac6ea", onSuccess, onFailure});
            }
        </script>
        ...
        ...
    </head>
    <body>
        ...
        ...
        <div id=”rch-dropin”></div>
        ...
        ...
    </body>
</html>

The onSuccess method passed into the init method indicates that the payment was successfully initiated, and you can redirect the shopper to the success page.

📘

NOTE

The onSuccess method does not indicate that the payment was completed only that the payment process has been successfully initiated. The payment is not complete until you’ve receive the ORDER_PROCESSED notification.

The onFailure method passed into the init method is called when an error that is unrecoverable inside the session is encountered. The error code and message will be passed into onFailure and can be used to determine which action to take. For example, a message could be displayed to the end user indicating what failed.

The Drop-In will notify you when it takes actions against a Session or Order. To receive these notifications, you must configure your server to listen for them by creating an endpoint at the webhook URL provided to Reach during onboarding. See the Notifications Guide for more details.

You will receive a SESSION_COMPLETED and ORDER_AUTHORIZED notification once the user has submitted their payment. Once the ORDER_AUTHORIZED notification is received, you can mark the Order as ready to be captured in your system.

📘

NOTE

The SESSION_COMPLETED is an informational notification that simply indicates the user has completed their interaction with the Drop-In. It should be logged but not actioned on.

The ORDER_AUTHORIZED notification will look like this:

{
  "EventType": "ORDER_AUTHORIZED",
  "Order": {
    "OrderId": "cc7236aa-d11b-436c-a29c-d26cecadc847",
    "State": "PAYMENT_AUTHORIZED",
    "MerchantReference": "unique_reference_provided_by_merchant",
    "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea"
  }
}

Upon successfully receiving a notification, you should respond with HTTP status 200. If you reply with a status outside that range, we will resend the notification later. See the Notifications Guide for more details.

When you are ready to Capture the Order, send an HTTP POST to the Order API. You will need the OrderId either from within the ORDER_AUTHORIZED notification or by looking up the Session via an API call to get the embedded OrderId (Session.Order.OrderId).

See the Reach Order API Reference for a more in-depth view of the Capture Order request.

   #Location
   POST https://api.withreach.com/v1/order/{OrderId}/capture

   #Headers
   Authorization: Basic YWNjb3VudDpzZWNyZXQ=
   
   #Body
   <empty>

   #Headers
   Content-Type: application/json
   
   #Body
   {
     "OrderId": "cc7236aa-d11b-436c-a29c-d26cecadc847",
     "State": "PROCESSED",
     "MerchantReference": "1234567890",
     "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea",
     "Reason": {
       "Code": "Captured",
       "Retryable": false
     }
   }

There are three different successful responses you can receive from the Capture Order request:

1. Captured: The Order was successfully captured.
2. PendingNotification: The Order capture attempt was successful. However, due to our third-party processor, the capture is pending completion, and you will be notified once it is completed.
3. UnderReview: The Order capture attempt was successful. Completion of the capture is pending an internal review being done by Reach’s team, and you will be notified once completed.

See the Reach Order API Reference for a more in-depth view of the Capture Order response.

Not all capture Order requests will be synchronous. If this was the case for your capture Order request, you will need to wait for the ORDER_PROCESSED notification to mark your Order as complete/captured.

The ORDER_PROCESSED notification will look like this:

{
  "EventType": "ORDER_PROCESSED",
  "Order": {
    "OrderId": "cc7236aa-d11b-436c-a29c-d26cecadc847",
    "State": "PROCESSED",
    "MerchantReference": "unique_reference_provided_by_merchant",
    "SessionId": "91b64778-0d37-479c-ae9f-32f6685ac6ea"
  }
}

Upon successfully receiving a notification, you should respond with HTTP status 200. If you reply with a status outside that range, we will resend the notification later. See the Notifications Guide for more details.