Authorisation
Authorization API (v2)
Getting Started
API Endpoints
- Server To Server
- Tokenization
- Subscriptions
- Wallet
- Hosted Payment Page
Error and Response
Webhook
Authorisation
Authorization API (v2)
Authorize a payment by securing funds for a transaction without capturing them immediately.
POST
/
api
/
v1
/
server-to-server-interface
/
authorizationv2
curl --request POST \
--url https://api-dev.paymentoptions.com/api/v1/api/v1/server-to-server-interface/authorizationv2 \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"amount": "1000",
"currency": "JPY",
"card": {
"cvc": "100",
"expiry_month": "12",
"expiry_year": "24",
"name": "John Doe",
"number": "5200000000001005"
},
"merchant_txn_ref": "qwe",
"customer_ip": "127.0.0.1",
"merchant_id": "< Merchant ID >",
"return_url": {
"webhook_url": "< Webhook url >",
"success_url": "http://www.successurl.com/",
"decline_url": "http://www.declineurl.com/"
},
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"shipping_address": {
"country": "JP",
"email": "shipping@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"browser_info": {
"acceptHeader": "text/html",
"screenColorDepth": "48",
"javaEnabled": false,
"language": "en",
"screenHeight": "1200",
"screenWidth": "1600",
"challengeWindow": "4",
"userAgent": "Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)"
},
"time_zone": "Asia/Kuala_Lumpur"
}'
{
"success": true,
"status_code": 201,
"is_live": false,
"transaction_type": "PRE_AUTH",
"gateway_response": {
"version": "1",
"type": "INFO",
"message": "Payment Successful.",
"code": "INFO0000"
},
"merchant_details": {
"legal_name": "Tink15 Factory",
"mid": "< Merchant ID >",
"merchant_txn_ref": "qwe",
"billing_details": {
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
}
},
"device_details": {
"visited_ip": "127.0.0.1",
"customer_ip": "127.0.0.1"
}
},
"payment_details": {
"amount": 1000,
"response_code": 0,
"auth_code": "917290",
"currency": "JPY",
"payment_method": "ECMC-SSL",
"scheme": "MASTERCARD",
"card": {
"name": "John Doe",
"number": "5200000000001005",
"exp_month": "12",
"exp_year": "24"
},
"additional_data": {
"payment_data_source": {
"type": "card"
}
}
},
"transaction_details": {
"id": "ab8444e7-fec0-40dd-994d-0ad813785f74",
"ref": 74797,
"timestamp": "2024-11-25T07:22:48.000Z",
"merchant_txn_ref": "qwe",
"stored_payment_method_id": null
},
"risk-details": {
"risk_score": null
}
}
Key Points
-
The Authorization API secures the specified amount on the customer’s payment method, but the funds are not transferred until a capture is performed.
-
Capture: Finalizes the transaction by transferring the authorized funds from the customer’s account.
-
Void: Cancels the authorization, releasing the held funds back to the customer.
-
Use cases for this API include scenarios where the exact final amount may vary, such as hotel bookings, car rentals, or pre-order situations.
Flow diagram
Api Parameters
Authorizations
API Key for Authorization. Format: 'Basic YOUR_API_KEY_HERE'
API Key specific to x-api-key.
Body
application/json
The request payload to authorize a payment transaction.
The body is of type object
.
Response
201 - application/json
Payment authorized successfully
The response is of type object
.
curl --request POST \
--url https://api-dev.paymentoptions.com/api/v1/api/v1/server-to-server-interface/authorizationv2 \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"amount": "1000",
"currency": "JPY",
"card": {
"cvc": "100",
"expiry_month": "12",
"expiry_year": "24",
"name": "John Doe",
"number": "5200000000001005"
},
"merchant_txn_ref": "qwe",
"customer_ip": "127.0.0.1",
"merchant_id": "< Merchant ID >",
"return_url": {
"webhook_url": "< Webhook url >",
"success_url": "http://www.successurl.com/",
"decline_url": "http://www.declineurl.com/"
},
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"shipping_address": {
"country": "JP",
"email": "shipping@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"browser_info": {
"acceptHeader": "text/html",
"screenColorDepth": "48",
"javaEnabled": false,
"language": "en",
"screenHeight": "1200",
"screenWidth": "1600",
"challengeWindow": "4",
"userAgent": "Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)"
},
"time_zone": "Asia/Kuala_Lumpur"
}'
{
"success": true,
"status_code": 201,
"is_live": false,
"transaction_type": "PRE_AUTH",
"gateway_response": {
"version": "1",
"type": "INFO",
"message": "Payment Successful.",
"code": "INFO0000"
},
"merchant_details": {
"legal_name": "Tink15 Factory",
"mid": "< Merchant ID >",
"merchant_txn_ref": "qwe",
"billing_details": {
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
}
},
"device_details": {
"visited_ip": "127.0.0.1",
"customer_ip": "127.0.0.1"
}
},
"payment_details": {
"amount": 1000,
"response_code": 0,
"auth_code": "917290",
"currency": "JPY",
"payment_method": "ECMC-SSL",
"scheme": "MASTERCARD",
"card": {
"name": "John Doe",
"number": "5200000000001005",
"exp_month": "12",
"exp_year": "24"
},
"additional_data": {
"payment_data_source": {
"type": "card"
}
}
},
"transaction_details": {
"id": "ab8444e7-fec0-40dd-994d-0ad813785f74",
"ref": 74797,
"timestamp": "2024-11-25T07:22:48.000Z",
"merchant_txn_ref": "qwe",
"stored_payment_method_id": null
},
"risk-details": {
"risk_score": null
}
}