Build Your Own Optty Payment Method Plugin
Optty
Optty allows retailers and other partners to add, configure and manage multiple payment providers through a single integration into either a partner’s platform or gateway and / or a retailers website.
Once new payment methods are added into the Optty library, then all current and future Optty clients have access to that payment method without the need for making any updates or changes (in some cases where payment flows are substantially different to the dataflow and UX outlined below, specific changes may be required, our support team will be happy to discuss this in detail if required).
Build Your Own Integration for Optty
This ‘living’ guide is designed to document the process a payments provider’s developer team would need to follow to interface directly with a standard set of Optty dataflows and API calls.
As new features are added into the Optty core platform this document will be updated from time to time to reflect those changes.
Abstract
Optty is a set of standardised mapping and configuration options that allow a retailer or partner to easily add and configure a new payment to an existing Optty integration.
The configuration of a payment method is handled by either the Optty web-based application, the Universal Payments Platform (UPP) or direct use of the external services that comprise the UPP.
For a consumer to process a transaction via the Optty integration, Optty must be first integrated into a retailer platform, or a partners payment flow that is already available in a retailer’s checkout flow.
For a deeper understanding of the overall Optty solution, it is recommended that readers of this document also familiarise themselves with the overall Optty Developer Documentation [https://docs.optty.com].
In some cases – specifically where an asynchronous flow is required – additional guidelines and support may be required. If you need more detailed explanation or further support, please contact us at [email protected]
Process
Once your integration is ready for testing, please notify us via [email protected] at which point we will require some endpoint information from you to commence the testing from Our perspective. We will also require your sandbox access credentials and consumer data from you to complete our end-to-end QA process.
During the QA process we will require a technical lead from your team to assist in any issue arising from the testing and QA process.
Once completed and ready to deploy to the Optty staging and production application your payment method will be available to existing Optty clients (in the appropriate countries and currencies) and any future Optty clients.
Please note – that our Payments team ([email protected]) should also be in contact to sign any paperwork that may be required.
If you need more detailed explanation or further support, please contact us at [email protected]
This document serves as a guide to build custom “Buy Now, Pay Later” Optty-compatible APIs and transaction flows for easy integration into the Optty Payment System ecosystem. To integrate with the Optty ecosystem, the Payment System is required to expose specific API endpoints and must have an existing form of authentication.
The below flow diagram describes how Optty interacts with the Payment Method, merchant and client when an order is placed.
The following are the API requirements for a Payment Method to provide for an easy integration with Optty.
- 1.API Authentication
- 2.Create Order Endpoint
- 3.Get Order Endpoint
- 4.Refund Order Endpoint
The Payment Method must have a means of authentication and authorization and must take the form of OAuth, Basic Authentication (username & password) or JWT Authentication Headers.
This is important as clients provide such authentication credentials to Optty when adding a Payment Method to their account. It is therefore important that Payment Methods that want to be integrated with Optty provide any of the fore-mentioned forms of authentication. For unauthenticated and unauthorized requests, the Payment Method should send the appropriate unauthorized HTTP status code.
A Payment Method that intends to be listed on Optty should have an endpoint to create an order. This would be the starting point for the credit application.
The create order endpoint would conventionally be an HTTP POST request and would accept any data field the Payment Method would want to have pertaining to an order. Below documents the properties required by Optty.
Create Order Payload Requirements:
Mandatory Fields
Field Name | Description | Example |
orderReference | This refers to the merchant's uniquely generated ID for an order. | UUID e.g. “c7eddf88-106d-416f-b3e8-3e4865cc839a” |
successUrl | This is the url that the user would be redirected to once the Payment Method has deemed the credit application successful from their hosted page. | |
failureUrl | This is the url that the user would be redirected to once the Payment Method declines the credit application from their hosted page. | |
errorUrl | This is the url that the user would be redirected to if an error occurred during or after supplying the Payment Methods required details on their hosted page. |
Just as there are required fields for creating an order over a Payment Methods API, the response should include certain required properties. Optty requires specific data fields be present in the create order response from a Payment Method
Create Order Response Requirements
Field Name | Description | example |
orderId | This refers to the unique identifier for the order on a Payment Methods system. This would be used by Optty to query the status of the order at a later stage. | UUID e.g.“c7eddf88-106d-416f-b3e8-3e4865cc839a” |
redirectUrl | This is a url that points to the Payment Methods hosted page. On this page, the applicant would fill in the necessary details a Payment Methods needs to approve or decline an application. |
Example Request/Response
URL: https://<bnpl-api-url>/order
METHOD: POST
PAYLOAD:
{
"orderReference": "order-1239434",
"redirects": {
},
"currency": "USD",
"state": "",
"region": "",
"country": "",
"cart": [
{
"itemName": "Versace Eros Flame",
"unitPrice": 100,
"numberOfItems": 1,
"totalPrice": 100
}
],
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+123456789"
}
}
RESPONSE:
{
"orderId": "bnpl-123453434",
"status": "PENDING"
}
A Payment Method that intends to be listed on Optty should have an HTTP endpoint to fetch an order. This endpoint should accept either the orderReference specified in the create order payload or the Payment Methods orderId returned in the create order response.
This endpoint would be an HTTP GET request and must return a status field that represents the current status of the order/application.
Below are the required fields Optty uses from the GET order response.
Get Order Response Requirements
Field Name | Description | Example |
orderId | This refers to the unique identifier for the order on a Payment Methods system. | UUID eg “c7eddf88-106d-416f-b3e8-3e4865cc839a” |
status | This field shows the current status of the order. | Eg PENDING, SUCCESS, DECLINED |
Example Request/Response
URL: https://<bnpl-api-url>/order/<order_id>
METHOD: GET
RESPONSE:
{
"orderId": "bnpl-123453434",
"status": "SUCCESS",
"merchantReference": "order-1239434",
"region":"",
"currency": "USD",
"country": "",
"cart":[...],
"customer": {...}
}
A Payment Method that intends to be listed on Optty should have an endpoint to refund an order. An order can either be refunded partially or in full.
The refund order endpoint should be an HTTP POST request. Documented below are the required properties for the endpoint.
Refund Order Request Requirements
Field Name | Description | Example |
refundReference | This is a unique reference sent by the merchant to identify a refund request. | UUID e.g. “c7eddf88-106d-416f-b3e8-3e4865cc839a” |
refundAmount | This is the amount to be refunded. It can either be a fraction of the total order amount or the total order amount. | E.g. 20, 30 |
refundCurrency | This is the currency value for the refund amount. | E.g. USD, EUR |
Example Request/Response
URL: https://<bnpl-api-url>/order/<order-id>/refund
METHOD: POST
PAYLOAD:
{
"reference":"refund-13924923",
"amount": 50,
"currency" : "USD",
"description": "Partial Refund for Versace eros flame"
}
RESPONSE:
{
"success": "true",
}
If you need more detailed explanation or further support, please contact us at s[email protected]
Last modified 1mo ago