Create Payment

Introduction

Payment Mode

Regular Payment

Regular payments refer to payments initiated directly by the merchant calling the payment creation interface without passing the mandate_id parameter, which requires the consumer to complete the payment process by performing the action specified in the action returned.

Direct Payment

Direct payment refers to the type of payment where the consumer does not have to pay himself when the mandate_id parameter is passed, the payment is completed by direct debit.

Subscription Payment

Subscription payment is a special form of direct payment. It cannot be created directly. Whenever a subscription is created successfully, the debt is automatically created by PiedPay each time the cycle is debited during the subscription lifecycle. Subscription payments support refunds just like regular payments.

Interface

POST /v1/payments

Request Params

Field	Name	Type	Range	Example	Default	Optional	Remark	Rule
reference	Reference	string	[1, 64]	2022123	optional	Refer to merchant side's customer ID, see Unique Reference Mode
payment_method	Payment Method	string	[1,64]		required	First name(and middle name if exists) of customer
flow	Flow	string	[1,64]		optional
terminal_type	Terminal Type	string	[1,64]		optional
currency	Currency	string			required
amount	Amount	string			required
customer_id	Customer ID	string			optional
mandate_id	Mandate ID	string			optional
return_url	Return URL	string			optional

flow

The default value depends on payment method

Value	Remark
indirect	including redirect to link, web URL, app, etc.
direct	including QR code, scan, ticket direct payment flow is always be direct(including subscription payment)

terminal_type

Only pass this param when flow = indirect

Value	Remark
web	Remark
app	default

customer_id

If the customer_id parameter is passed, it becomes possible to query the transaction history of this customer.

Only one of the customer_id and mandate_id params can be passed.

mandate_id

If the mandate_id parameter is passed, as long as the mandate is valid, the payment becomes a direct payment, this means the debit can be initiated directly without the consumer's action to pay. It also identifies which customer paid for it. For more detail about the mandate, visit: Create Customer Mandate

Only one of the customer_id and mandate_id params can be passed.

Response Params

payment.action

type = redirect_to_url

Example:

```json
{
    "type": "redirect_to_url",
    "redirect_to_url": {
        "url": "https://some-gateway.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?codeValue=281666040095AYuV1kHYR6Ixph30nX449BfS"
}
```

Instruction:

Redirect customer to APP URL to continue

type = redirect_to_app

Example:

```json
{
    "type": "redirect_to_app",
    "redirect_to_app": {
        "url": "alipays://platformapi/startApp?appId=10000007&actionType=route&qrcode=281666040091kpWB2tD6k9hJyn1kG1Vv3kSL&externalThrough=%7B%22acTerminalType%22%3A%22WAP%22%7D"
    }
}
```

Instruction:

Redirect customer to URL to continue

type = verify_otp

Example:

```json
{
    "type": "verify_otp"
}
```

Instruction:

Wait for the customer to receive OTP, gather OTP and call POST mandates/:mandate_id/verify API to continue

type = display_qr_code

Example:

```json
{
    "type": "display_qr_code",
    "display_qr_code": {
        "data": "00020101021226730014B...sHOarh630455D4",
        "image_url_svg": "",
        "image_url_png": ""
    } 
}
```

Instruction:

Display the QR code to the customer to continue

type = display_details

Example:

```json
{
    "type": "display_details",
    "display_details": {
        // fields here vary in different payment methods
    }
}
```

Example for boleto_br:

```json
{
    "type": "display_details",
    "display_details": {
        "code": "33299958000000100000001119018473501600286435",
        "number": "33290001151901847350416002864359995800000010000"
    }
}
```

Example for banktransfer_mx:

```json
{
    "type": "display_details",
    "display_details": {
        "country": "",
        "currency": "",
        "bank_name": "",
        "bank_code": "",
        "bank_branch_name": "",
        "bank_branch_code": "",
        "account_holder_name": "",
        "account_number": "",
        "reference": ""
    }
}
```

Example for paycash_mx:

```json
{
    "type": "display_details",
    "display_details": {
        "reference": ""
    }
}
```

Instruction:

Display the details to the customer to continue

Response Example

200 success:

{
  "id": "pm_SSqvfTHmfbrLbvDy50GCSKiP",
  "object": "payment",
  "livemode": false,
  "payment_method": "alipay_cn",
  "terminal_type": "web",
  "time_created": "2023-01-09T14:02:28+08:00",
  "time_paid": null,
  "time_expired": "2023-01-10T14:02:28+08:00",
  "reference": null,
  "source": "normal",
  "source_id": null,
  "customer_id": "cst_9W9unPGC0yzHjL4y",
  "currency": "CNY",
  "currency_local": "CNY",
  "amount": "0.05",
  "amount_paid": null,
  "amount_refunded": null,
  "amount_local_paid": null,
  "amount_local_refunded": null,
  "failure_message": null,
  "failure_code": null,
  "status": "created",
  "paid": false,
  "description": null,
  "action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://some-payment-method.com/pay.html"
    }
  },
  "metadata": {
    "custom_field": "custom_value"
  },
  "extra": {}
}