Payease CUP

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

API Version

Minimum required API version: 1.0.0




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

3DS 1.0 ExternalNo
3DS 1.0 InternalNo
3DS 2.0 ExternalNo
3DS 2.0 InternalNo
End-to-End Encryption (E2EE)No
Level 2 and 3 DataNo
Payment FacilitatorNo
Retrieve Supported Payment MethodsNo
Retrieve Supported PlansNo
Statement Soft DescriptorNo
Stored Credentials FlagNo
Transaction Processing without CVVNo


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

Charge Not ApplicableAsynchronous or SynchronousThe request mode is asynchronous in the event of a provider network error.
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.
Refund Both partial and multiple are supportedAsynchronous or SynchronousThe request mode is asynchronous in the event of a provider network error.

Setup Procedures

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

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)
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

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


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

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": ""
  2. An SMS confirmation code will be sent to your customer, using the 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.3.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.


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.

results matching ""

    No results matching ""