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
string · required

Set to application/json.


X-Portone-Client-Key
string · required

The unique PortOne key for the merchant.


Authorization
string · required

JWT for authenticating API requests. Learn how to generate the token here.


Steps to Create an On-Demand Deduction

  1. Setup the PortOne Key, Secret, and JWT Token: Ensure you have your PortOne Key, Secret, and JWT Token ready for authentication.
  2. Create Payload: Prepare the JSON request body with all required parameters.
  3. Generate Signature Hash: Generate the signature_hash as per the On-Demand Deduction Signature Documentation.
  4. Call the API: Use the endpoint to send the payload.
  5. 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
string · required

The unique PortOne key for the merchant.


signature_hash
string · required

Signature hash generated as per On-Demand Deduction Request Signature Documentation.


merchant_order_ref
string · required

The unique merchant order reference generated by the merchant.


subscription_order_ref
string · required

The unique subscription order reference of the subscription link.


description
string

Product name for the customer's subscription purchase.


source
string · required

The source of creation: default, api, or checkout.


amount
double · required

The amount of deduction (can be a floating-point number).


currency
string · required

The currency of the subscription (e.g., USD).


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 and live 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.