stable · api · 0.1.0

Create a Payment Transaction

POST /api/v1/payment-transactions

Capability Domain: Payments

Authentication

projectCredential (payments:write)

Scope: payments:write

Parameters and request body

Idempotency-Key — header, required
Idempotency-Key schema
```
{
    "type": "string",
    "maxLength": 120
}
```
X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "project_order_reference",
        "amount",
        "item_name",
        "trade_description"
    ],
    "properties": {
        "project_order_reference": {
            "type": "string",
            "maxLength": 180
        },
        "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 99999999
        },
        "item_name": {
            "type": "string",
            "maxLength": 200
        },
        "trade_description": {
            "type": "string",
            "maxLength": 200
        },
        "recurring": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "period_type",
                "frequency",
                "execution_count"
            ],
            "properties": {
                "period_type": {
                    "type": "string",
                    "enum": [
                        "D",
                        "M",
                        "Y"
                    ]
                },
                "frequency": {
                    "type": "integer",
                    "minimum": 1
                },
                "execution_count": {
                    "type": "integer",
                    "minimum": 1
                }
            }
        }
    }
}

application/json request example

{
    "project_order_reference": "sandbox-order-1001",
    "amount": 100,
    "item_name": "Sandbox item",
    "trade_description": "MiniCenter sandbox payment"
}

Responses and errors

Status	Description
`200`	Payment Transaction and signed provider checkout fields
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	Request violates the public contract

200 schema

200 response schema

{
    "type": "object",
    "required": [
        "data"
    ],
    "properties": {
        "data": {
            "type": "object",
            "required": [
                "id",
                "status",
                "checkout_url",
                "checkout_fields"
            ],
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "status": {
                    "type": "string",
                    "enum": [
                        "pending"
                    ]
                },
                "checkout_url": {
                    "type": "string",
                    "format": "uri"
                },
                "checkout_fields": {
                    "type": "object"
                }
            }
        }
    }
}

401 schema

401 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

403 schema

403 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

422 schema

422 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

200 example

200 response example

{
    "data": {
        "id": "70000000-0000-4000-8000-000000000007",
        "status": "pending",
        "checkout_url": "https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5",
        "checkout_fields": {
            "MerchantTradeNo": "MC2026073000000001",
            "TotalAmount": 100
        }
    }
}

Idempotency

Requires Idempotency-Key. Retry an uncertain request with the same key and unchanged body.