Payment
Version Requirements
- MiniApp SDK Version:
>= 2.5.0(npm package@wcm/mini-app-sdk) - MiniApp Runtime Engine Version:
>= 5.1.0
Basic Usage
import { PaymentSDK } from "@wcm/mini-app-sdk/payment";
const paymentSDK = new PaymentSDK({
env: "<your-environment>", // optional, default: "prod"
});
// First, you have to create a payment session on your backend and get a payment ID. Then, you can call the showPayment method with the payment ID to show the payment confirmation screen to the user.
await paymentSDK.showPayment({
paymentInfo:{
paymentId: "<your-payment-id>"
},
callbackPathnames: {
error: "/your-payment-error-pathname",
success: "/your-payment-success-pathname"
}
});
API Spec
{
"/mini-app-runtime/v2/projects/{project_id}/paymentsv2": {
"post": {
"tags": [
"runtime.payments"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"client_order_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"terminal_id": {
"type": "string"
},
"user_token": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"payment": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
}
},
"required": [
"amount",
"currency"
],
"additionalProperties": false
},
"purchased_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"quantity": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"tax_rate": {
"type": "number",
"exclusiveMinimum": true,
"minimum": 0
},
"price": {
"type": "number",
"exclusiveMinimum": true,
"minimum": 0
},
"original_price": {
"type": "number",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"id",
"name",
"quantity",
"tax_rate",
"price",
"original_price"
],
"additionalProperties": false
},
"minItems": 1
},
"tax_classifications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tax_amount": {
"type": "number"
},
"tax_rate": {
"type": "number"
},
"adjusted_total_amount": {
"type": "number"
},
"non_adjusted_total_amount": {
"type": "number"
},
"adjusting_amount": {
"type": "number"
}
},
"required": [
"tax_amount",
"tax_rate",
"adjusted_total_amount",
"non_adjusted_total_amount",
"adjusting_amount"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 3
},
"amount_adjustments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 2048
},
"adjust_unit_value": {
"type": "number"
},
"applied_item_count": {
"type": "number"
},
"target_item_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
},
"required": [
"reason",
"adjust_unit_value",
"applied_item_count",
"target_item_ids"
],
"additionalProperties": false
}
}
},
"required": [
"client_order_id",
"user_token",
"payment",
"purchased_items",
"tax_classifications"
],
"additionalProperties": false
}
}
},
"required": true
},
"parameters": [
{
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"name": "project_id",
"required": true
}
],
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
},
"info": {
"type": "string",
"minLength": 1
}
},
"required": [
"success",
"data",
"info"
],
"additionalProperties": false
}
}
}
}
}
}
}
}
detailed usage
Prerequisites:
- You received a Server Side Client secret upon creation of your first MiniApp version.
- You must contact MiniApp Platform team to create for you a tenant.
caution
This API must be used on the backend only; please avoid using it on the frontend to not expose your client secret.
Steps
First, you have to setup your backend (server side if you are using nextjs) to create a payment session and get a payment ID using the MiniApp Create Payment API.
Then, in your MiniApp, you can call the showPayment method with the payment ID to show the payment confirmation screen rendered by the MiniApp Runtime Engine to the user. You also need to provide callback pathnames for success and error scenarios, which will be used to handle the user's navigation after they complete or cancel the payment.
MiniApp Create Payment API
- Get Access Token
curl -d 'client_id={YOUR_KEYCLOAK_CLIENT_ID}' \
-d 'client_secret={YOUR_KEYCLOAK_CLIENT_SECRET}' \
-d 'grant_type=client_credentials' \
'https://id.woven-city.toyota/auth/realms/woven/protocol/openid-connect/token'
- Create Payment
curl -X POST 'https://mini-app-api.lab.woven-city.toyota/mini-app-runtime/v2/projects/{project_id}/paymentsv2' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"client_order_id": "123456789",
"terminal_id": "terminal_1",
"user_token": "access_token_upon_seamless_login",
"payment": {
"amount": 100.00,
"currency": "USD"
},
"purchased_items": [
{
"id": "item_1",
"name": "Product 1",
"quantity": 2,
"tax_rate": 0.1,
"price": 50.00,
"original_price": 60.00
}
],
"tax_classifications": [
{
"tax_amount": 10.00,
"tax_rate": 0.1,
"adjusted_total_amount": 90.00,
"non_adjusted_total_amount": 100.00,
"adjusting_amount": 10.00
}
],
"amount_adjustments": [
{
"reason": "Discount",
"adjust_unit_value": 5.00,
"applied_item_count": 2,
"target_item_ids": ["item_1"]
}
]
}'