This call is used to initiate a payment from a merchant or PSP. Once the payment is initiated, in most cases further client or user input is required. The payment will be completed by the user, and the result returned to the merchant or PSP via the callback URLs. If callback URLs are included in the payment request, they will be used. If callback URLs are not included in the payment request, the default URLs for the merchant or PSP, stored at the MYGW Gateway when the merchant was added will be used. URLs: Test https://api.test.oneroadpayments.com/merchants/{merchantID}/transactions Production https://api.oneroadpayments.com/merchants/{merchantID}/transactions Request Method: POST URL Parameters: Name | Description | M/O | merchantID | The unique merchant ID provided by the PSP or allocated by the MYGW system | M |
Payment Transaction Request Body Name | Description | M/O | clientID | Key or name to identify the customer, depending on the merchant this may be managed by the merchant or by the MYGW-CM system. Some merchants are required to include a valid clientID or new client object | O | amount | The amount of the purchase transaction | M | cardType | The type of payment card or account to be used for the transaction. Depending on the merchant this can be one of 'UnionPay', 'Alipay' or 'Wechat Pay' | M | currency | The transaction currency. This must match a currency setup for the merchant at sign up | M | echo | Value echoed back at the point of notification. This is not used during transaction authorization | O | orderID | The unique merchant order number for this transaction. This is used by the merchant or PSP to identify transactions with the MYGW server if required | M | replyURL | The ‘front end’ URL, called by MYGW-PM once the transaction completes with the result of the transaction. This URL will be displayed to the client to inform them of the result of the transaction. If this field is not set or left blank, the URL stored on the server for the merchant/PSP will be used | O | backofficeURL | The merchant or PSP back-end server URL called when a transaction completes with the result of the transaction. If this field is not set or left blank, the URL stored on the server for the merchant/PSP will be used | O | sendEmail | Flags whether the Email Pay process (see above) should be used to process this transaction. This is only relevant is the merchant is registered for Email Pay for this cardType | O | signature | The cryptographic hash for this payment transaction, created using the Merchant Key, used to authenticate the payment request | M | signatureVersion | Indicates the version of the signature to authenticate this transaction. Currently '1.0' | M | client | If a new client is being created for this transaction, contains the client object described above | O |
The payment request should be sent to the MYGW Gateway server using the POST method. In most cases this call is used to initiate a payment and as described above, this will result in the client or user being redirected to a separate transaction page to complete payment. This can be done by entering card or account details; scanning a QR code and/or entering an authentication code (in the case of 3DS for example) to complete the payment. Merchants and PSPs are notified of the result of the payment transaction by way of the callback URLs described in the payment fields above. Payment Transaction Response The MYGW server will respond including a status code, signifying whether the call succeeded, as described above - MYGW API Responses. This response relates to the payment API call; a success response does not mean the payment transaction has completed successfully, only that the payment initiation process has successfully started. The final result of the payment transaction is sent using the callback URLs. The response to the payment request includes in the field response HTML code to redirect the user to the required payment page. An example of the data sent in a response to a successful payment request is as follows. { status: 200, response:”<?xml version="1.0" encoding="UTF-8"?><html class="mac chrome chrome5 webkit webkit5"><head><base href="/"><meta http-equiv="refresh" content="0;url=https://payments.oneroadpayments.com/redirect2.html?curr=036&merc=SE&id=tc8d94856-db35-4f85-b7c7-e96a0b11d5d5&stage=test&amt=10000&m=5adeaafb-1b6d-4bb2-ba11-1cce35e6b38e&o=108029257&sign=027ae8d96fc5e41d3e79372efd1f4e24&time=20240716133512&order=20240716969339133512"/></head><body></body></html>” } Rendering the code in the response field will redirect the client or user to the payment page to complete the payment transaction. An example of the JSON object sent in a response to an unsuccessful payment request is as follows. { "response": { "statusCode":400, "message":"Bad Request", "detail":"Amount out of range - for this merchant; USD [min = 1.00, max = 15000.00]" } } An example of how to process error conditions is included above under MYGW API Responses.
The status code and status message returned could be one of the following values.
Status Code | Description | Status Message | 200 | The payment request was successfully initiated, and the response includes the redirect HTML code | Message - NA | 210 | The payment request was successfully initiated, and a payment enablement email has been sent to the client. Used with Email Pay | Message - NA | 400 | The transaction amount is out of range for the merchant. Transaction ranges are allocated to merchants at sign up | Message - Bad Request Detail – Amount out of range for this merchant | 400 | The presenting currency is not supported for this merchant. Merchants are allocated a set of currencies at sign up | Message - Bad Request Detail – Currency not supported for this merchant | 400 | The signature included in the request could not be verified using the Merchant Key | Message - Bad Request Detail – Signature mismatch | 404 | The merchant ID was invalid or not recognised | Message – Not Found Detail –Merchant not found | 404 | A client ID was included in the payment request, and it could not be recognised as belonging to the merchant | Message – Not Found Detail –Client record not found | 422 | The order number in the payment request has been used with a previous transaction and the order cannot be completed | Message – Unprocessable Entity Detail –Duplicate Order ID | 422 | No path to the requested payment system could be found for this transaction or merchant. This error most often occurs when a merchant has not been enabled for the cardType specified in the payment request. | Message – Unprocessable Entity Detail – Unable to determine gateway processor | 422 | The merchant has exceeded their daily, weekly, fortnightly or monthly transaction or volume limit. Merchants are allocated their limits at sign on | Message – Unprocessable Entity Detail – Blocked due to risk score Reason - Exceed transaction attempts | 500 | A server error occurred, and the request failed | Message – Internal processing exception |
Note: Other reasons for the payment request failing may include risk management parameters, limits or ranges being exceeded. In every case the status will be 422 and the response will include message, detail and optionally reason fields. When any of the errors listed above are returned (i.e. the status codes except 200 and 210), it means that the transaction has not been initiated and there is no further action taken with that transaction. In this case, no callback is sent to the reply or backend URL and processing of the transaction is complete. Callback URL Processing When the response to the payment request is either 200 or 210, it means that the transaction has been initiated and will complete at some time in the future. The final result of this transaction will be notified to the client or user via a callback to the replyURL and to the merchant or PSP via a callback to the backofficeURL. The structure of the URL callback is the same for the replyURL and the backofficeURL, as follows for a successful transaction https://{callbackURL}?currency=AUD&success=Y&merchantID=5adeaafb-1b6d-4bb2-ba11-1cce35e6b38e&orderID=110836419&clientID=NewClient&amount=25.00&signature=3a53e1e7251b08036cc2f9b8de9d2030 and as follows for a failed transaction https://{callbackURL}?success=N&merchantID=5adeaafb-1b6d-4bb2-ba11-1cce35e6b38e&orderID=110836419&clientID=NewClient&detail=Transaction+abandoned&signature=1ef02c01f953aec4163bc06d4c287c6f The signature URL parameter is used to verify that the callback originated from the MYGW Gateway. The signature is generated in a similar way to the signature included in the payment request, except that the merchant ID is appended to the data to be signed. The same Merchant Key is used to generate and verify the signature in the callback URL. The callback is sent using the GET method. An example of executable JavaScript sample source code to verify the URL signature can be found by clicking on the icon below. Note that this is an example of how a URL signature can be verified, it is a not a recommendation for how to implement callbacks in your own applications. .png)
Payment Request - Sample Source Code An example of executable JavaScript sample source code to initiate a payment can be found by clicking on the icon below. Note that this is an example of how a payment request can be initiated, it is a not a recommendation for how to implement the payment APIs in your own applications.
| 
