Implement KaKaoPay on Adyen Integration v2.0
Support for the KaKaoPay payment method on Adyen can be requested through the Specialized Payment Connections service at an additional cost.
Overview
KaKaoPay is one of the most popular e-wallets in Korea. Zuora's Adyen Integration v2.0 supports KaKaoPay transactions in KRW currency. You can implement a hosted payment page through Payment Pages 2.0 to support KaKaoPay one-time and recurring payment flows.
One-time payment flow
On the hosted payment page, a QR code is displayed. End customers can follow the instructions on the page to complete the authorization. The following table describes the workflows after Zuora receives a successful or failed response from the Adyen asynchronous payment API.
Response | Workflow |
---|---|
Successful response |
|
Failed response |
Zuora throws an error on the hosted payment page with the error response message received from Adyen. |
The created KaKaoPay payment method can be retrieved through the Zuora UI and API operations. You can also retrieve the following token information in the Electronic Payment Methods section of the customer account page. Token ID and Second Token ID will be used in subsequent recurring payments.
Zuora UI field | Value |
---|---|
Token ID | shopperReference |
Second Token ID | recurringDetail |
Third Token ID | first payment merchantReference |
Recurring payments flow
Recurring payments are processed with the stored tokens. For details about the recurring payment flow for the end customers, see Adyen's documentation.
Supported and unsupported features
The following table lists the supported and unsupported operations and features for KaKaoPay on Adyen Integration v2.0:
Supported | Unsupported |
---|---|
|
|
Overall implementation procedure
Overall, complete the following steps to implement a KaKaoPay payment flow to support one-time or recurring payments:
- Prepare for the integration.
- Set up a Payment Page 2.0.
- Request a signature from Zuora for the payment page.
- Set up your client code to integrate the payment page to your web page.
- Implement the callback response.
You can find detailed instructions in the following sections.
Step 1. Prepare for the integration
Before implementing the KaKaoPay payment method on Adyen, ensure that all prerequisites outlined in the following sections are fulfilled.
KaKaoPay enablement and configuration
- Ensure you have requested support for KaKaoPay on Adyen Integration v2.0 through the Specialized Payment Connections service.
- Complete the following steps to activate the KaKaoPay payment method type on your tenant:
- Click your username in the upper right and navigate to Settings > Payments > Payment Method.
- Click Edit at the bottom of the page.
- Select KaKaoPay and click Save.
Adyen gateway instance configuration
To configure an Adyen gateway instance for processing KaKaoPay transactions, follow the instructions in Set up and configure an Adyen Integration v2.0 gateway instance.
In particular, you can skip the following requirements and settings as they do not apply to KaKaoPay transactions.
Prerequisites |
The last two prerequisites are not applicable to KaKaoPay:
|
Credentials |
|
Rules |
|
Additional Metadata |
KaKaoPay does not support Additional Metadata. |
For the following settings, specific values are passed to the gateway, regardless of the values configured in these settings in the UI.
Setting | Value passed to Adyen |
---|---|
Shopper Interaction |
There is no way to override these values. |
Recurring Processing Model |
Subscription If you want to override it, use the param_gwOptions_recurringProcessingModel gateway options field. |
Real-Time Reconciliation setup
To process KaKaoPay transactions, you must turn on Real-Time Reconciliation. Follow the instructions in Enable and configure Real-Time Reconciliation for Adyen Integration v2.0.
Features required for payment flow implementation
- To support processing authorization amounts, the following features must be turned on:
- Validate Client-Side HPM Parameters
Follow the instructions in Client-side Payment Page parameter to enable it. - Either Credit Balance or Invoice Settlement
- Validate Client-Side HPM Parameters
- To support processing invoices, the following requirements must be met:
- Validate Client-Side HPM Parameters must be enabled.
- The invoices must be posted before the invoices are paid through the one-time payment.
- To understand the implementation procedure of Payment Pages 2.0 in Zuora, review Payment Pages 2.0 implementation overview.
Step 2. Create and configure a KaKaoPay payment page
Complete the following steps to create and configure a KaKaoPay payment page:
- In Zuora UI, navigate to Settings > Payments, and click Setup Payment Page and Payment Link.
- On the Payment Pages tab page, configure the tenant-level settings for the hosted payment page.
- In the Type dropdown list, select KaKaoPay.
- Click Create New Hosted Page.
- In the Basic Information section, specify the following fields:
Field Description Page Name
Enter a name for your hosted payment page. This name is used to identify your payment page in Zuora. It is different from the title displayed on the payment page. You can specify the title in the Page Title field in the Page Configuration section.
Hosted Domain
Enter the domain address from which your payment page is served. This domain also hosts your callback page. The value must be in the format: https://www.domain.com.
Zuora validates this field for you. If the validation fails, an error message is displayed on the payment page. Note that the Overlay Hosted Page mode does not support the hosted domain validation.
If you want your hosted payment pages and callback pages to reside in the subdomain of the hosted domain, enable the tenant-level Allow Subdomain Callback for Hosted Pages setting.
Callback Path
Enter the path on which the callback page file resides. Zuora appends this to the Hosted Domain entry to create the full URL to which the callback is sent. Specify a value in the format: /app/callback_file.jsp. The file extension, such as .jsp or .php, is not required. However, the callback path must begin with a forward slash character ( / ).
The Callback Path is only required for the advanced implementation option, which uses the inline style form with an external submit button. This setting is ignored for the basic setup, which uses the overlay form or the inline form with the submit button inside.
- In the Default Payment Gateway field of the Payment Gateway section, click and select an Adyen Integration v2.0 instance. Note that Zuora does not validate this setting. You can override this default gateway in your request by specifying a gateway through the paymentGateway client parameter.
- In the Page Configuration section, complete the field configuration.
Field Description Page Title
Enter a title for the hosted payment page. Select Display to display the Page Title on this payment page.
Page Description
Enter the description of the payment page. Select Display to display the Page Description on this payment page.
Submit Button
This field is not applicable to KaKaoPay. Skip it.
Client-Side Validation
This setting is not applicable to KaKaoPay. Skip it.
CSS
This field is not applicable to KaKaoPay. Skip it.
- Click Generate and Save Page.
Subsequently, you can preview the form.
Step 3. Request a signature for the Payment Page
Follow the instructions in Request a signature for the Payment Page from Zuora. Because the Client-side HPM Parameter Validation feature is enabled, Zuora will validate the additional fields in the request by comparing them with the values specified in the digital signature.
Here are two request examples for the Generate RSA signature REST API operation.
{ "uri":"https://sandbox.na.zuora.com/apps/Pu...tedPageLite.do", "method":"POST", "pageId":"test808145b3bf9d0145b3c6812b0008", "paymentGateway":"Adyen", "authroizationAmount":"100", "currency":"KRW", "accountId":"test808145b3bf9d0145b3c6812b0008" }
{ "uri":"https://sandbox.na.zuora.com/apps/Pu...tedPageLite.do", "method":"POST", "pageId":"test808145b3bf9d0145b3c6812b0008", "paymentGateway":"Adyen", "accountId":"test808145b3bf9d0145b3c6812b0008" }
Step 4. Set up your client code
Follow the instructions in Integrate Payment Pages 2.0. When rendering the Payment Page form, specify the following required parameters in the Z.render or Z.renderWithErrorHandler function. For other optional parameters, see Client Parameters for Payment Pages 2.0.
Required Parameter | Description |
---|---|
doPayment |
Type: boolean Default: false true indicates that the Payment Page will create a payment method as well as process the one-time payment transaction. If it is false or not specified, the Payment Page will only create a payment method. To implement KaKaoPay payment flows, doPayment must be true. |
storePaymentMethod |
Type: boolean Default: true true indicates that the payment method will be stored in Zuora and used in subsequent recurring payments. false indicates that the payment method will not be stored in Zuora. End customers need to be brought back to session to authenticate the payment. |
field_accountId |
Type: string Example: 8a90e5e48f2eade6018f2ed19133003a Zuora customer account ID. This account must be set up with the KRW currency. The payment method will be created for this specified account. |
authorizationAmount |
Required for authorization amount processing The amount of the one-time payment that will be sent to the gateway. For more information about this parameter, see Client parameters for Payment Pages 2.0. |
field_currency |
Required for authorization amount processing The currency of the one-time payment amount. Only KRW is supported by Adyen KaKaoPay. For more information about this parameter, see Client parameters for Payment Pages 2.0. |
documents |
Required for invoice processing An array of invoices to be paid in this transaction, containing the following fields:
|
Here is an example of the parameters for the payment flow for processing the first one-time and subsequent recurring payments:
var params = { doPayment:"true", storePaymentMethod:"true", field_accountId:"testc0f87596f2f301759c29443622fa", documents:"[{"type":"invoice","ref":"INV00026338"}, {"type":"invoice","ref":"INV00026339"}]" };
Step 5. Implement the callback response
See Advanced Integration of Payment Pages 2.0 for more information.