Create Customer Mandate

Introduction

Create a customer mandate

The mandate object represents a mandate operation, normally it belongs to a customer. This allows PiedPay to deduct funds directly from your customer in recurring scenarios typically, or make a direct payment, without having to care about the details.

PiedPay's subscriptions feature utilizes mandate objects, and you can also use mandates to build your own subscription services.

Interface

POST /v1/customers/:customer_id/mandates

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
terminal_type	Terminal Type	string	[1,64]		optional
return_url	Return URL	string			optional

terminal_type

Only pass this param when flow = indirect

Value	Remark
web	Remark
app	default

Response Params

action.type

same as payment.action

extra

extra.payment_method_account

In some cases, such as e-wallet payment method, the consumer's wallet account information would be returned.

Field	Remark
reference	Consumer's account ID (maybe phone number/email/login id etc.)
name	Consumer's name
balance_amount	Consumer's balance amount
balance_currency	Consumer's balance currency

```json
"extra": {
  "payment_method_account": {
      "reference": "consumer***@gmail.com",
      "name": null,
      "balance_amount": null,
      "balance_currency": null
  }
}
```

For each payment method, payment_method_account return includes:

payment method	reference	name	balance_amount & balance_currency
alipay_cn	e.g. abc***@someprovider.com	NA	NA
dana_id	phone number, e.g. 62-857****6606	NA	NA
shopeepay_id	NA	NA	NA
ovo_id	phone number, e.g. +6281888XXXX	NA	returned
rabbitlinepay_th	e.g. ***นันท์	NA	NA
truemoney_th	e.g. +66*****5353	NA	NA
kakaopay_kr	e.g. mo****bl@kakao.com	NA	NA
card_ru	e.g. 220015******4603	NA	NA
...	...	...	...

Best Practice

Best Practices

Multiple mandates can be created per customer for each payment method (maximum of 5), but it is not recommended to create repeated mandates on the business initiation side, as long as the mandate is still active, it can always be used for debiting.

Before create payment and subscription through mandate, it is recommended to do enough guidance to allow consumers to recharge enough debit amount to reduce the debit failure rate.

Response Example

200 success:

{
  "id": "mdt_jLCGGKjj5anLavDq",
  "object": "mandate",
  "payment_method": "touchngo_my",
  "terminal_type": "web",
  "gateway_transaction_id": "lKCB7uWF9kKohpiB",
  "customer_id": "cst_ir5Ki9Su90WDSOWj",
  "status": "pending",
  "time_signed": null,
  "time_created": "2022-07-18T11:54:54+08:00",
  "failure_message": null,
  "failure_code": null,
  "extra": {},
  "action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://g.alipayplus.com/page/aplus-linker/acwallet/authorization.html?scopes=AGREEMENT_PAY%2CUSER_LOGIN_ID&bizContent=%7B%22acquirerId%22%3A%22Z02TE0230000000A%22%2C%22authClientId%22%3A%22800039253992185%22%2C%22authClientName%22%3A%22AllPay%20International%20Limited%22%2C%22authRedirectUrl%22%3A%22https%3A%2F%2Frender.alipay.com%2Fp%2Fw%2Fac-fe-adaptor%2Fadaptor.html%3FaccessType%3Dback%26markuid%3D0A%26callbackType%3DCommon%26terminalType%3DWEB%26referenceAgreementId%3D540eff8f9d09e6edafc474f355ec85e6%26authRequestId%3D2022071819091305000900000101696%26pspId%3D102217100000000000A%26clientId%3DTEST_305XST2CSG0N4P05595%22%2C%22authState%22%3A%22e07b6b8d-6aa0-4530-b52e-4199ce4eef3b%22%2C%22customerBelongsTo%22%3A%22TNG%22%2C%22pspId%22%3A%22102217100000000000A%22%2C%22referenceAgreementId%22%3A%22540eff8f9d09e6edafc474f355ec85e6%22%2C%22referenceMerchantId%22%3A%22800039253992185%22%2C%22scopes%22%3A%5B%22AGREEMENT_PAY%22%2C%22USER_LOGIN_ID%22%5D%2C%22terminalType%22%3A%22WEB%22%7D&source=AlipayConnect&needCallback=true"
    }
  }
}