Payease CUP

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications described below.

• API Version
• Payment Methods
• Currencies
• Features
• Requests
• Setup Procedures
• Integration Procedures
• Testing

API Version

Minimum required API version: 1.0.0

Payment Methods

UnionPay credit and debit cards (domestic) - CUP (China Union Pay). For list of supported banks, contact Payease.

Currencies

CNY

Features

The following table provides an overview of all supported and non-supported features.

Feature	Supported
3DS Data from External MPI	No
3DS Redirection	No
Installments	No
Statement Soft Descriptor	No
Stored Credentials Flag	No
Transaction Processing without CVV	No

Requests

The following table lists all supported requests for card-based transactions. Use the bodybuilder to create a sample request body for each request type.

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

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.

1. 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.

2. Use the RSA private key value as the private key credential (see the Configurations table above).

3. 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.

The phone-based authentication flow has the following steps:

1. 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"
        }
    }
   

2. 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.

3. Prompt your customer to enter the SMS confirmation code that was sent to them.

4. 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.

5. 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.