Creating an On-Demand Deduction
This document provides a comprehensive guide to creating an On-Demand Deduction using the PortOne API. Merchants can perform deductions for subscriptions based on specific usage or amounts.
API Endpoint
POST https://api.portone.cloud/api/subscription/deduct
Headers
Content-Type
Content-Type
string · required
Set to application/json
.
X-Portone-Client-Key
X-Portone-Client-Key
string · required
The unique PortOne key for the merchant.
Authorization
Authorization
string · required
JWT for authenticating API requests. Learn how to generate the token here.
Steps to Create an On-Demand Deduction
- Setup the PortOne Key, Secret, and JWT Token: Ensure you have your
PortOne Key
,Secret
, andJWT Token
ready for authentication. - Create Payload: Prepare the JSON request body with all required parameters.
- Generate Signature Hash: Generate the
signature_hash
as per the On-Demand Deduction Signature Documentation. - Call the API: Use the endpoint to send the payload.
- Handle the Response: Process the response to confirm the deduction's status.
Request Example
On-Demand Deduction Request
Request Body:
{
"portone_key": "PORTONE_KEY",
"merchant_order_ref": "Merchant_1729672233763",
"subscription_order_ref": "2nsRMeHXpSUpe8DZzdyZkKCtI9D",
"description": "Product name for the customer's subscription purchase",
"source": "api",
"amount": 100,
"currency": "USD",
"environment": "sandbox"
}
Request Body Parameters
portone_key
portone_key
string · required
The unique PortOne key for the merchant.
signature_hash
signature_hash
string · required
Signature hash generated as per On-Demand Deduction Request Signature Documentation.
merchant_order_ref
merchant_order_ref
string · required
The unique merchant order reference generated by the merchant.
subscription_order_ref
subscription_order_ref
string · required
The unique subscription order reference of the subscription link.
description
description
string
Product name for the customer's subscription purchase.
source
source
string · required
The source of creation: default
, api
, or checkout
.
amount
amount
double · required
The amount of deduction (can be a floating-point number).
currency
currency
string · required
The currency of the subscription (e.g., USD
).
environment
environment
string · required
The environment of the transaction, either sandbox
or live
.
Response
Success Response
{
"is_success": true,
"merchant_order_ref": "Merchant_1729672233763",
"order_ref": "2nsRMeHXpSUpe8DZzdyZkKCtI9D",
"status_code": "200",
"status": "success"
}
Error Response
{
"is_success": false,
"message": "The API request failed due to invalid parameters.",
"status_code": "400",
"status_reason": "Bad Request"
}
Best Practices
- Environment Selection: Use
sandbox
for testing andlive
for production. - Validation: Validate all required fields before sending the request.
- Monitoring: Regularly monitor deduction statuses and logs.
This document serves as a comprehensive guide to creating On-Demand Deductions using the PortOne API.
Updated 5 days ago