Direct API Integration

Full Flexibility, allowing you to tailor your checkout flow any way you like.

Overview
Just a  few simple steps to access to Payment Methods across the world
Step 1: OAuth - Creating an access token
Step 2: Get Merchant’s Config
Step 3: Create Order 
Step 4: Redirect Customer to Payment Method
Return to your URL and process the order based on payment status
Step 1 - OAuth: Create an access token
post
https://auth.qa.optty.com
/token?expires_in=1
optty authentication
Step 2 - Get Payment Method options
get
https://api.qa.optty.com
/options/
GET Payment Method Request
Sample Query Format
Sample Curl Request
Sample Response
https://api.qa.optty.com/options/?currency=SGD&amount=100
curl -X GET "https://api.qa.optty.com/options?amount=100&currency=SGD" \
-H "accept: application/json" \
-H "Authorization: Bearer {YOUR ACCCESS TOKEN}"
[
    {
        "terms": "Pay SGD 33.33 weekly over 3 weeks with Hoolah SG.",
        "name": "HOOLAH_SG",
        "imageUrl": "https://widgets.qa.optty.com/images/logos/bnpl_hoolah_1.0.png",
        "instalment": {
            "rate": {
                "amount": 33.33,
                "currency": "SGD"
            },
            "termDuration": 3,
            "termUnit": "weeks"
        },
        "monthlyCost": {
            "amount": 100,
            "currency": "SGD"
        },
        "termDurationInMonths": 0.75,
        "weeklyCost": {
            "amount": 33.33,
            "currency": "SGD"
        },
        "termDurationInWeeks": 3,
        "recommended": true,
        "checkoutConfig": {
            "content": "",
            "iframeUrl": "",
            "button": {
                "type": "global",
                "text": "Checkout",
                "color": "#FFFFFF",
                "background": "#0E77C6",
                "position": "left",
                "size": "small"
            },
            "termsCondition": {
                "type": "none",
                "content": "",
                "linkText": "Terms & Condition"
            }
        },
        "currency": "SGD",
        "maxAmount": "10000",
        "minAmount": "1",
        "priority": "24",
        "lateFeesAllowed": false,
        "customerFeesAllowed": false,
        "interestRateAllowed": false,
        "interestRate": "0",
        "ratings": 0,
        "ratingsAvailabilityStatus": false
    }
]
Step 3 - Create Order 
post
https://api.qa.optty.com
/orders/
Placing an Order
See Create Order for the details of each request fields. 
FULL Sample Request and Response
Sample Request Object
Sample Curl Request
Sample Response
content-type application/json:
{
   "bnplProvider":"LATITUDEPAY_AU",
   "locale":"en_AU",
   "customerToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkZW50aWZpZXIiOiI5OWIwODI1MDA4OTUxMDNjMmNjNTNiZmNhMGVlZTNjOTdjMjE2MGM4ZGFhMGM0MmQ4NmI3M2M4NWU5NjA0NTE5ZGEzMDI4MWE3MjlhYzYwMWZjYzMyZDc4ZTdjZmQ1NmJkMjllNjIwZTI2YWU0ZTYzYTRjZTVlOTc2NWE2ZjA3NCIsIm1lcmNoYW50SWQiOiJkNmJiZmQ5Zi02OWZhLTQ3MjgtOTU0YS04MWU0NWI4YWFkMmQiLCJpYXQiOjE2MDE2NjAwMTUsImV4cCI6MTYwMTY2MzYxNX0.Y0UKdtSNPVnJlLN3Xv53Y1_o2AbLPhjxJ1P5O0DSpnE",
   "orderReference":"LP000_OrderID",
   "orderAmount":144.89,
   "taxAmount":6.9,
   "shippingAmount":7.99,
   "discountAmount":0,
   "purchaseCountry":"AU",
   "purchaseCurrency":"AUD",
   "orderItems":[
      {
         "name":"Optty Striped Dress Shirt",
         "quantity":1,
         "sku":"69309284M-1",
         "unitPrice":130,
         "totalAmount":130
      }
   ],
   "customer":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"[email protected]",
      "phoneNumber":"(415) 200-0000"
   },
   "billingAddress":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"[email protected]",
      "phoneNumber":"(415) 200-0000",
      "streetAddress":"Your Address",
      "streetAddress2":"Your Address2",
      "city":"Sydney",
      "country":"AU",
      "region":"Oceanian",
      "postalCode":"2000",
      "state": "NSW"
   }
   "shippingAddress":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"[email protected]",
      "phoneNumber":"(415) 200-0000",
      "streetAddress":"Your Address",
      "streetAddress2":"Your Address2",
      "city":"Sydney",
      "country":"AU",
      "region":"Oceanian",
      "postalCode":"2000",
      "state": "NSW"
   }
   "shippingType": "normal",
   "shippingMethod": "store pick-up",
   "dynamicRedirectUrl": "YOUR_URL"
}
curl -X POST "https://api.qa.optty.com/orders" \
-H "accept: application/json" \
-H "Authorization: Bearer {YOUR ACCCESS TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"bnplProvider\":\"LATITUDEPAY_AU\",\"locale\":\"en_AU\",
\"customerToken\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkZW50aWZpZXIiOiI5OWIwODI1MDA4OTUxMDNjMmNjNTNiZmNhMGVlZTNjOTdjMjE2MGM4ZGFhMGM0MmQ4NmI3M2M4NWU5NjA0NTE5ZGEzMDI4MWE3MjlhYzYwMWZjYzMyZDc4ZTdjZmQ1NmJkMjllNjIwZTI2YWU0ZTYzYTRjZTVlOTc2NWE2ZjA3NCIsIm1lcmNoYW50SWQiOiJkNmJiZmQ5Zi02OWZhLTQ3MjgtOTU0YS04MWU0NWI4YWFkMmQiLCJpYXQiOjE2MDE2NjAwMTUsImV4cCI6MTYwMTY2MzYxNX0.Y0UKdtSNPVnJlLN3Xv53Y1_o2AbLPhjxJ1P5O0DSpnE\", 
\"orderReference\":\"LP000_OrderID\",\"orderAmount\":144.89,\"taxAmount\":6.9,\"shippingAmount\":7.99,\"discountAmount\":0,
\"purchaseCountry\":\"AU\",\"purchaseCurrency\":\"AUD\",\"orderItems\":[{\"name\":\"Optty Striped Dress Shirt\",\"quantity\":1,
\"sku\":\"69309284M-1\",\"unitPrice\":130,\"totalAmount\":130}],\"customer\":{\"firstName\":\"Your FirstName\",\"lastName\":\"Your LastName\",
\"email\":\"[email protected].test\",\"phoneNumber\":\"(415) 200-0000\"},\"billingAddress\":{\"firstName\":\"Your FirstName\",
\"lastName\":\"Your LastName\",\"email\":\"[email protected].test\",\"phoneNumber\":\"(415) 200-0000\",\"streetAddress\":\"Your Address\",
\"streetAddress2\":\"Your Address2\",\"city\":\"Sydney\",\"country\":\"AU\",\"region\":\"Oceanian\",\"postalCode\":\"2000\",\"state\":\"NSW\"}}"
content-type application/json:
{
    "orderId": "LP000429e48ec-f6e3-49d2-bd38-8e1408d025c8",
    "orderToken": "5d47c4a0-9bfc-406d-9da1-bbc61202c722",
    "redirectUrl": "https://app.uat.latitudepay.com/r/NVXIFQBC",
    "bnplProvider": "LATITUDEPAY_AU",
    "orderReference": "LP000429e48ec-f6e3-49d2-bd38-8e1408d025c8",
    "orderAmount": 144.89,
    "orderPaymentOption": "buy now pay later",
    "orderDate": "2021-10-07T14:30:36.166Z",
    "paymentStatus": "pending"
}
Using the redirectURL from the response 
eg: "redirectUrl": "https://app.BNPL.com/r/NVXIFQBC" redirect the user to the payment method website, for processing the Payment. 
​
More details on Create Order refer to API References documents. 
See also the Order response object.
Step 4 - Handling Payment Response 
After payment for an order has occurred, Optty performs the necessary confirmations and redirects to the merchant.
The following data is returned in the redirect back to the merchant, as query strings.
Parameter
Type
Description
hash
string
The hash being returned to the merchant for verification.
reference
string
The reference provided by the merchant; can be used for lookups.
status
string
The state of the transaction
Possible Value:
SUCCESSFUL 
CANCELED 
DECLINED
providerReference
string (optional)
The reference provided by the Payment Method provider; can be used to do lookups directly on the Payment Method provider.
Example Redirect URL
http://example.com?hash=coqCmt%2FIZ4E3CzPvMY8zTjQVL5hYJUiBRg8UU%2BiCWo0&reference=1234&status=SUCCESSFUL&providerReference=c4dbe976f7
To protect your server from unauthorized redirects, we strongly recommend that you verify the HMAC signature by attempting to re-create the signature, by hashing with the merchant secret, and only honour the redirect if it matches.
To calculate the hash value, concatenate the 'status' and 'reference' parameters (using a pipe "|" to delimit the values) and generate a hash using the SHA512 algorithm.
Current hashed string contents - {status}|{reference}
Compare the base64 encoded value of the recreated signature with the request hash, If there is no match, then the redirect may be compromised and it should not be trusted.
Dynamic URL
The Payment Response will be send to the default URL setup in your Optty account. 
However, if you would like to override the return URL, you could send dynamicRedirectUrl in the Create Order API Fields. It will be override the default URL and redirect your customer to the URL that you sent in the Create Order Request, after the payment is completed.  
​
See Also
Create Order
Refund Order
​

Widget - Previous

Widget Setup and Integration

Next - API References

Create Order

Last modified 16d ago

Parameter	Type	Description
hash	string	The hash being returned to the merchant for verification.
reference	string	The reference provided by the merchant; can be used for lookups.
status	string	The state of the transaction Possible Value: SUCCESSFUL CANCELED DECLINED
providerReference	string (optional)	The reference provided by the Payment Method provider; can be used to do lookups directly on the Payment Method provider.