# Authenticated Payment
Authenticated payment refers to a payment process where the payer's identity and authorization are verified before the transaction is completed. This type of payment typically involves an additional layer of security to ensure that the person making the payment is the rightful owner of the account or card being used.
Depending on the authentication method used, the payer may be redirected to their bank's website or app to provide additional verification, such as a one-time password (OTP), biometric authentication, or other forms of identity confirmation.
TIP
Call the Payment endpoint to authorize a payment
# Example using full card details
Live
Sandbox
POST: https://api.openacquiring.com/v1/merchants/YOUR_MERCHANT_ID/payment
Request example
- Shell
- JavaScript
curl -X POST \
https://api.openacquiring.com/v1/merchants/w3z8dfhkzvfq0j9n/payment \
-H 'authorization: Basic ODZidWQ0Y2JremlxOXZmYzoweHI1ZDkwOHo2bmo4a2h6' \
-H 'content-type: application/json' \
-d '{
"intent": "sale",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"number": "4005520201264821",
"expire_month": 12,
"expire_year": 2020,
"cvv2": "123",
"name": "Tom Hanks"
}
},
"payer_info": {
"email": "TomHanks@gmail.com",
"billing_address": {
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "mu",
"postal_code": "72101",
"state": "",
"phone": {
"country_code": "230",
"number": "57976041"
}
}
}
},
"payee": {
"email": "mail@test.com",
"merchant_id": "w3z8dfhkzvfq0j9n"
},
"transaction": {
"amount": {
"currency": "OMR",
"total": "3",
"details": {
"subtotal": "",
"shipping": ""
},
"return_url": "https://myreturnurl.com/return"
},
"description": "purchase",
"items": [{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "20",
"currency": "USD",
"url": "",
"image": "",
"tangible": "true"
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "20",
"currency": "USD",
"url": "",
"image": "",
"tangible": "true"
}
],
"shipping_address": {
"recipient_name": "Tom Hanks"
},
"soft_descriptor": {
"text": "test.com",
"city": "london"
},
"invoice_number": "123455"
},
"custom": {
},
"capture_delay": 0.05,
"metadata": {
"CMS": "WooCommerce"
}
}'
Response example
{
"id": "35ZQXK7H9YRD17JI6DNU",
"reference_id": "35ZQXK7H9YRD17JI6DNU",
"state": "authorised",
"result": {
"redirect_url": "https://api.openacquiring.com/v1/redirect/9c22d2084e2547f88d32c0e6d97c17c2",
"authenticate_url": "https://api.openacquiring.com/v1/authenticate/9c22d2084e2547f88d32c0e6d97c17c2",
"code": "1007"
},
"intent": "AUTH",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "9c22d208-4e25-47f8-8d32-c0e6d97c17c2",
"type": "Visa",
"expire_month": 12,
"expire_year": 2020,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "4821",
"bin": "400552",
"is_default": true,
"bin_data": {
"bin": "400552",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "0f053a05-9fa2-49a1-871f-3098e4b114e2",
"email": "TomHanks@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "OMR",
"total": "3"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"recipient_name": "Tom Hanks",
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"delayed_capture_time": "2020-09-06T21:53:18Z",
"create_time": "2020-09-06T21:50:18Z",
"three_d": {}
}
# Request
# Header parameters
The request require a Basic authentication in the header. For more information about HTTP request headers, see HTTP request headers.
# Request parameters
| Parameter | Type | Description |
|---|---|---|
| merchant_id required | string | Encrypted Merchant account identifier for the Merchant |
# Request body
| Parameter | Type | Description | Value |
|---|---|---|---|
| intent required | enum | Encrypted Merchant account identifier for the Merchant | sale. Makes an immediate payment. auth. Authorizes a payment for capture later |
| payer required | object | The source of the funds for this payment | |
| transaction required | object | Defines what the payment is for and who fulfills the payment | |
| payee | object | The payee who receives the funds and fulfills the order | |
| custom | object | Free-form field for the use of clients | |
| capture_delay | decimal | The payment will be captured after the number of hours that you specify, - If Value is not specified and intent is Auth, then the transaction should be captured manually. - If Value is specified and equal to 0 and intent is AUTH, then the transaction is captured after the default period of 7 days. - If Value is specified and intent is AUTH, then the transaction is captured after the specified number of hours. | Value cannot be > 168 hours (7 days) |
| metadata | ArrayOf(KeyValuePair(string, string)) | Contains additional information about the transaction |
# Response
TIP
Successful response will contain a redirect_url. You must redirect the customer to this URL in order to finalize the OTP flow.
status 200
status 400
status 422
{
"id": "35ZQXK7H9YRD17JI6DNU",
"reference_id": "35ZQXK7H9YRD17JI6DNU",
"state": "authorised",
"result": {
"redirect_url": "https://api.openacquiring.com/v1/redirect/9c22d2084e2547f88d32c0e6d97c17c2",
"authenticate_url": "https://api.openacquiring.com/v1/authenticate/9c22d2084e2547f88d32c0e6d97c17c2",
"code": "1007"
},
"intent": "AUTH",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "9c22d208-4e25-47f8-8d32-c0e6d97c17c2",
"type": "Visa",
"expire_month": 12,
"expire_year": 2020,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "4821",
"bin": "400552",
"is_default": true,
"bin_data": {
"bin": "400552",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "0f053a05-9fa2-49a1-871f-3098e4b114e2",
"email": "TomHanks@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "OMR",
"total": "3"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"recipient_name": "Tom Hanks",
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"delayed_capture_time": "2020-09-06T21:53:18Z",
"create_time": "2020-09-06T21:50:18Z",
"three_d": {}
}
# Response Body
# Status 200 Success
| Parameter | Type | Description | Value |
|---|---|---|---|
| id | string | Identifier of the payment resource created | |
| reference_id | string | In case of referenced payment (e.g., Capture or Refund), this fields included to see which payment was referenced | |
| state | string | The state of the payment, authorization, or order transaction | - Authorised. The transaction was successfully authorised.- Pending. The transaction is currently pending.- Captured. The transaction has been captured.- Refunded. The transaction has been refunded.- Declined. The transaction has been declined.- Expired. The transaction has been expired.- Cancelled. The transaction has been cancelled.- Voided. The transaction has been voided.- Timeout. The transaction has been timeout.- Deferred Refund. The transaction refund has been deferred.- Flagged. The transaction has been flagged.- Deferred Capture. The transaction Capture has been deferred.- Card Verified. The card has been verified. |
| result | object | Contain result of the payment request | |
| intent | string | The payment intent | - sale. Makes an immediate payment.- auth. Authorizes a payment for capture later |
| payer | object | Source of the funds for this payment represented by a direct credit card | |
| payee | object | A resource representing a Payee who receives the funds and fulfills the order | |
| transaction | object | Transactional details including the amount and item details | |
| custom | object | Free-form field for the use of clients | |
| create_time | datetime | Payment creation time as defined in RFC 3339 Section 5.6 | |
| three_d | object | ThreeD Secure details pertaining to the transaction | |
| delayed_capture_time | datetime | Payment capture time in case the capture is delayed. (as defined in RFC 3339 Section 5.6 | |
| metadata | ArrayOf( KeyValuePair(string, string)) | contains additional information about the transaction |
# Error Response Body
# Status 400 Bad Request
| Parameter | Type | Description |
|---|---|---|
| code | string | Code indentifying the error on our system |
| name | string | Name indentifying the error on our system |
| message | string | Message related to the error |
| eventId | string | Unique Identifier for the request |
# Status 422 Unprocessable Entity
The request was well-formed but was unable to be follewed due to semantic errors.
| Parameter | Type | Description |
|---|---|---|
| eventId | string | Unique Identifier for the request |
| errors | arrayOf(error) | Array of errors |
# errors object
| Parameter | Type | Description |
|---|---|---|
| code | string | Code indentifying the error on our system |
| name | string | Name indentifying the error on our system |
| message | string | Message related to the error |
# Authenticate the payment
For enhanced convenience, merchants have the option to capture One-Time Passwords (OTPs) directly through their own web forms. Rather than redirecting customers based on the redirect_url, merchants can integrate a customized web form on their website or application to securely collect OTPs. This feature allows for a seamless user experience while maintaining control over the authentication process. To do so use the following API endpoint.
WARNING
This flow will only work only if the aquirer is OmanNet
Live
Sandbox
This endpoint is dynamic and generated in the response of the initial response
POST: https://api.openacquiring.com/v1/authenticate/PAYMENT_SESSION_ID
Request example
- Shell
- JavaScript
curl -X POST \
https://api.openacquiring.com/v1/authenticate/9c22d2084e2547f88d32c0e6d97c17c2 \
-H 'authorization: Basic ODZidWQ0Y2JremlxOXZmYzoweHI1ZDkwOHo2bmo4a2h6' \
-H 'content-type: application/json' \
-d '{
"reference_id":"auth"
,"otp": "111111"
}'
Response example
{
"id": "35ZQXK7H9YRD17JI6DNU",
"reference_id": "35ZQXK7H9YRD17JI6DNU",
"state": "authorised",
"result": {
"authorisation_code": "058607",
"risk_check": true,
"code": "0000"
},
"intent": "SALE",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "9c22d208-4e25-47f8-8d32-c0e6d97c17c2",
"type": "Visa",
"expire_month": 12,
"expire_year": 2020,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "4821",
"bin": "400552",
"is_default": true,
"bin_data": {
"bin": "400552",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "0f053a05-9fa2-49a1-871f-3098e4b114e2",
"email": "TomHanks@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "OMR",
"total": "3"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"recipient_name": "Tom Hanks",
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"delayed_capture_time": "2020-09-06T21:53:18Z",
"create_time": "2020-09-06T21:50:18Z",
"three_d": {}
}
# Request
Authenticate a sale using the OTP capture from the payer. Note that this url is retrieved from the initial payment call and is a one time use (once called the payment session will expire).
# Header parameters
The request require a Basic authentication in the header. For more information about HTTP request headers, see HTTP request headers.
# Request parameters
| Parameter | Type | Description |
|---|---|---|
| payment_session_id required | string | Identifier of the payment session |
# Request body (authenticate payment object)
| Parameter | Type | Description |
|---|---|---|
| reference_id required | string | Identifier referencing the payment |
| otp required | string | One time password. (on sandbox this is always 111111) |
# Response
status 200
status 400
status 422
{
"id": "35ZQXK7H9YRD17JI6DNU",
"reference_id": "35ZQXK7H9YRD17JI6DNU",
"state": "authorised",
"result": {
"authorisation_code": "058607",
"risk_check": true,
"code": "0000"
},
"intent": "SALE",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "9c22d208-4e25-47f8-8d32-c0e6d97c17c2",
"type": "Visa",
"expire_month": 12,
"expire_year": 2020,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "4821",
"bin": "400552",
"is_default": true,
"bin_data": {
"bin": "400552",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "0f053a05-9fa2-49a1-871f-3098e4b114e2",
"email": "TomHanks@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "OMR",
"total": "3"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"recipient_name": "Tom Hanks",
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"delayed_capture_time": "2020-09-06T21:53:18Z",
"create_time": "2020-09-06T21:50:18Z",
"three_d": {}
}
# Response Body
# Status 200 Success
| Parameter | Type | Description | Value |
|---|---|---|---|
| id | string | Identifier of the payment resource created | |
| reference_id | string | In case of referenced payment (e.g., Capture or Refund), this fields included to see which payment was referenced | |
| state | string | The state of the payment, authorization, or order transaction | - Authorised. The transaction was successfully authorised.- Pending. The transaction is currently pending.- Captured. The transaction has been captured.- Refunded. The transaction has been refunded.- Declined. The transaction has been declined.- Expired. The transaction has been expired.- Cancelled. The transaction has been cancelled.- Voided. The transaction has been voided.- Timeout. The transaction has been timeout.- Deferred Refund. The transaction refund has been deferred.- Flagged. The transaction has been flagged.- Deferred Capture. The transaction Capture has been deferred.- Card Verified. The card has been verified. |
| result | object | Contain result of the payment request | |
| intent | string | The payment intent | - sale. Makes an immediate payment.- auth. Authorizes a payment for capture later |
| payer | object | Source of the funds for this payment represented by a direct credit card | |
| payee | object | A resource representing a Payee who receives the funds and fulfills the order | |
| transaction | object | Transactional details including the amount and item details | |
| custom | object | Free-form field for the use of clients | |
| create_time | datetime | Payment creation time as defined in RFC 3339 Section 5.6 | |
| three_d | object | ThreeD Secure details pertaining to the transaction | |
| delayed_capture_time | datetime | Payment capture time in case the capture is delayed. (as defined in RFC 3339 Section 5.6 | |
| metadata | ArrayOf( KeyValuePair(string, string)) | contains additional information about the transaction |
# Error Response Body
# Status 400 Bad Request
| Parameter | Type | Description |
|---|---|---|
| code | string | Code indentifying the error on our system |
| name | string | Name indentifying the error on our system |
| message | string | Message related to the error |
| eventId | string | Unique Identifier for the request |
# Status 422 Unprocessable Entity
The request was well-formed but was unable to be follewed due to semantic errors.
| Parameter | Type | Description |
|---|---|---|
| eventId | string | Unique Identifier for the request |
| errors | arrayOf(error) | Array of errors |
# errors object
| Parameter | Type | Description |
|---|---|---|
| code | string | Code indentifying the error on our system |
| name | string | Name indentifying the error on our system |
| message | string | Message related to the error |