Payease CUP

Payease-CUP has some special integration requirements. Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications described below.

Specifications for Card-based Transactions

The following table lists the integration specifications for Payease-CUP.

Specifications	Details
Minimum PaymentsOS API Version	1.1.0
Requests	Charge Refund (including multiple/partial) Supported Charge flows: Non-recurring shopper flow (SMS-based customer authentication): Recurring shopper flow (no SMS authentication) The type of Charge flow that is invoked is determined by the `sms_validation_required` field, which you may optionally pass in the `provider_specific_data` object of the Charge request. For an example, use the Bodybuilder to generate a Charge request with optional fields.
Currencies	CNY
Payment Methods	UnionPay credit and debit cards (domestic) - CUP (China Union Pay). For list of supported banks, contact Payease.
3DS Redirection	Not supported

Configurations

The following table lists the configurations that are specific to Payease-CUP.

Configuration	Required/Optional
In the PaymentsOS Control Center, configure the following credentials: mid: The merchant id defined in Payease. sha2_key: The secret key provided by Payease. refund_operation_id: The Operator Number assigned by Payease for refunds. private-key: This is an RSA private key created by you (this is not the same as the PaymentsOS private key)	Required
In the PaymentsOS Control Center, register webhooks to be notified when a transaction changes its status.	Required
In your Payease CUP account, set your configuration to either the non-recurring shopper flow (requires the customer to enter an SMS validation code for each purchase) or the recurring shopper flow (does not require an SMS validation code). Contact Payease CUP support for assistance.	Required

Sample Requests

Use the bodybuilder to create a sample request body for each request type.

Creating an RSA Key Pair

An RSA key pair is used to encrypt and decrypt sensitive data (card number, cvv, etc.), sent between PaymentsOS and Payease. These keys are not provided by Payease, and should be created by you.

Create an RSA key pair. For details of how to create RSA Key Pairs (for both Mac and Windows), see Generating a keypair using OpenSSL.
Use the RSA private key value as the private key credential (see the Configurations table above).
Send the RSA public key (certificate) to Payease. When sending the public.cert, always include the following "prefix" and the "suffix", before and after, as shown in this example:
```
 -----BEGIN CERTIFICATE-----
 MIIEogIBAAKCAQEAmFK8vdmykVggoyXH
 ...
 Mi7pMXd7ypsE/Y6pTA4zFj4lOiAnQ1Q=
 -----END CERTIFICATE-----
```

Implementing an SMS Phone-based Authentication Flow (Non-recurring Shopper Flow)

Payease-CUP payments for the non-recurring shopper flow require phone-based authentication via SMS, and real-time number verification.

Note

Make sure that your Payease account is configured for the non-recurring shopper flow.

The phone-based authentication flow has the following steps:

Send a post charge request.

 {
   "reconciliation_id": "14807764988811"
   "payment_method": {
       "type": "tokenized",
       "token": "f78cbf5b-0e23-44e0-be11-2081791d9501",
       "credit_card_cvv": "123"
       }
     }
 }

You'll receive a post charge response with a status of pending, and a provider_data.additional_information.callback_url (you will use the callback_url later.):

 {
   "provider_name": "Payease-CUP",
   "response_code": "0",
   "description": "Success",
   "additional_information": {
       "transaction_status": "sms_confirmation_pending",
       "callback_url": "https://api.paymentsos.com/payments/0269f212-bd23-48ae-a944-be9a8e926ada/charges/3716e0a3-1139-441c-af16-bebbb19ca0f7/callbacks?q=NmNiMDU4YTMtMTgxMy00N2UzLTlhYmEtNjAzOTBmODNiNzk2Y3Z2X2RlbGltaXRlcnZhdWx0OnYx2jR2R1FWeUMrbnNPdTZ6dG1KWEpCRmgweHMyZml0czFxSm5KRTlxWUJWMlot"
     }
 }

An SMS confirmation code will be sent to your customer, using the payment.billing_address.phone number that you provided in the post payment request.
Prompt your customer to enter the SMS confirmation code that was sent to them.

When you receive the SMS confirmation code from your customer, send a post to the callback_url, containing sms_confirmation_code as the body:

 POST /payments/ac804fbf-ae74-4a49-8d63-5ae95e98bdfa/charges/3716e0a3-1139-441c-af16-bebbb19ca0f7/callbacks
 Content-Type: application/json
 api-version: 1.2.0
 x-payments-os-env: live
 app-id: com.zooz.payeaseapp
 private-key: 4a960bae-d5ef-466c-bf42-40e243d82388
 idempotency-key: fba975c6-4f27-1e81-9004-4415b8720228
 {
     "sms_confirmation_code": "1234"
 }

You will receive a response of HTTP code 204 (without a response body), if your post containing the SMS confirmation code was sent to Payease successfully.

Query the payment/charge to get the payment status (Succeed or Failed). For this you can either:
- Create Webhook notifications (see the Webhooks Guide)).
- Send requests to query the status of the payment or charge resources.

Re-sending a new SMS Confirmation Code to your Customer

You can re-send a new SMS confirmation code to your customer, as long as the previous sms_confirmation_code was not used, (the process above, did not reach step 5).

Repeat the steps above, but note the few important changes. Re-send the post charge request, with the following conditions:

Use the same reconciliation_id.
Use a different idempotency-key in the request header.

Testing

Payease does not have a testing/sandbox environment. We therefore recommend you perform initial tests in the PaymentsOS test environment using the mock provider. Then continue testing in the Payease live environment, using live Unionpay cards.