Skip to main content

UnionPay

Overview

UnionPay is a a Chinese financial services company headquartered in Shanghai, China. 

Founded on 26 March 2002, UnionPay is a payment method available worldwide, but very popular in APAC countries. It supports recurring payments.

In 2015, UnionPay overtook Visa and Mastercard in a total amount of value of payment transactions becoming the largest card payment processing company in the world surpassing the two. Only 0.5% of this payment volume was outside of China.

In 2020, UnionPay reported more than 151 billion worldwide transactions on its network. 

While most users are from China, UnionPay cards can be used in 180 countries and regions around the world. Some UnionPay credit cards are also affiliated with American Express, MasterCard, or Visa.

Availability

This payment method is available in China, Macau, Hong Kong, and Singapore.

Supported currencies

CNY, USD, EUR, GBP, AUD, CAD, CHF, JPY, PLN, SEK, RUB, BRL, ZAR.

Workflow

When placing the order, shoppers input a UnionPay card as normal. The accepted processing currency needs to be CNY, USD, EUR, GBP, AUD, CAD, CHF, JPY, PLN, SEK, RUB, BRL, ZAR. 

  1. When placing the order, shoppers input a UnionPay card as normal.
  2. The accepted processing currency needs to be CNY, USD, EUR, GBP, AUD, CAD, CHF, JPY, PLN, SEK, RUB, BRL, ZAR.
  3. The payment then continues as a normal Card order.

UnionPay Shopping Cart

Retrying the payment for an order

Overview 

Customers can retry making a payment if the initial payment fails, without placing a new order. The customer can use other payment details or a different payment method.  

Availability 

Available for all orders placed via API and on all packages. 

Request example 

To retry a payment for an already placed order, provide the order reference number in the Place Order API call in the RefNo parameter placed in the root of the request object. 

{ 
   "Language":"en", 
   "Country":"US", 
   "CustomerIP":"10.10.10.10", 
   "RefNo":"123456622", 
   "Source":"Website", 
   "ExternalCustomerReference":"externalCustomerId", 
   "Currency":"USD", 
   "MachineId":"123456789", 
   "Items":[ 
      { 
         "Code":"5DCB30C6B0", 
         "Quantity":1 
      } 
   ], 

   "BillingDetails":{ 
      "FirstName":"Customer First Name", 
      "LastName":"Customer Last Name", 
      "CountryCode":"US", 
      "State":"California", 
      "City":"San Francisco", 
      "Address1":"Example Street", 
      "Zip":"90210", 
      "Email":"example@email.com" 
   }, 
   "PaymentDetails":{ 
      "Type":"TEST", 
      "Currency":"USD", 
      "PaymentMethod":{ 
         "CardNumber":"4111111111111111", 
         "CardType":"VISA", 
         "ExpirationYear":"2023", 
         "ExpirationMonth":"12", 
         "HolderName":"John Doe", 
         "CCID":"123", 
         "Vendor3DSReturnURL":"http:\/\/yoursuccessurl.com", 
         "Vendor3DSCancelURL":"http:\/\/yourcancelurl.com" 
      }, 
      "CustomerIP":"10.10.10.10" 
   } 
} 

 

Retrieve partner invoice templates

Overview

Use the getPartnerInvoiceTemplates method in Channel Manager to retrieve templates of partner invoices.

   This API method is available only on API version 6.0.

Request parameters

Parameter name Type Required/Optional Description
sessionID String Required Output of the Login method.

Request example

<?php

declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'getPartnerInvoiceTemplates';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{  
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object
    {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }

        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url . '?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
       // $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

 Response

[
    {
        "IdInvoiceTemplate": "1",
        "TemplateName": "Compact Listing"
    }
]

 

Retrieve partner invoice templates

Overview

Use the getPartnerInvoiceTemplates method in Channel Manager to retrieve templates of partner invoices.

   This API method is available only on API version 6.0.

Request parameters

Parameter name Type Required/Optional Description
sessionID String Required Output of the Login method

Request example

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = 'MALWARQO';
    public const MERCHANT_KEY = 'SECRET_KEY';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'getPartnerInvoiceTemplates';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{  
}
JSON;
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
        return compact('merchantCode', 'date', 'hash');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();

        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }

        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload];
        }
        $payload = array_filter($payload);

        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);

        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response

[
    {
        "IdInvoiceTemplate": "1",
        "TemplateName": "Compact Listing"
    }
]

 

Retrieve partner users

Overview

Use the getPartnerUserAPI method in Channel Manager to retrieve users for a specific partner.

   This API method is available only on API version 6.0.

Request parameters

Parameter name Type Required/Optional Description
uuid String Required Partner unique identifier.
email String Required Email of the partner-user.
sessionID String Required Output of the Login method.

Request example

<?php
declare(strict_types=1);
class Configuration
{
public const MERCHANT_CODE = '';
public const MERCHANT_KEY = '';
public const URL = 'http://api.2checkout.com/rpc/6.0';
public const ACTION = 'getPartnerUser';
public const ADDITIONAL_OPTIONS = null;
//array or JSON
public const PAYLOAD = <<<JSON
["95fbb26a-43d6-482a-8544-d07f942aec8d", "test@test.com"]
JSON;
}


class Client
{
private const LOGIN_METHOD = 'login';
private $calls = 1;
private $sessionId;
private function generateAuth(): array
{
$merchantCode = Configuration::MERCHANT_CODE;
$key = Configuration::MERCHANT_KEY;
$date = gmdate('Y-m-d H:i:s');
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);
return compact('merchantCode', 'date', 'hash');
}
public function login(string $url)
{
$payload = $this->generateAuth();
$response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
$this->sessionId = $response['result'];
}
public function call(
string $url = Configuration::URL,
$payload = Configuration::PAYLOAD,
string $action = Configuration::ACTION
): ?array {
if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
$this->login($url);
}
if(is_string($payload)) {
$payload = json_decode($payload, true);
}

if (!empty($this->sessionId)) {
if (is_array($payload)) {
$payload = array_merge([$this->sessionId], $payload);
} else {
$payload = [$this->sessionId, $payload];
}

}
$payload = array_filter($payload);



$request = json_encode([
'jsonrpc' => '2.0',
'method' => $action,
'params' => $payload,
'id' => $this->calls++,
]);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSLVERSION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($curl);
if(empty($response)) {
die('Server unavailable');
}
echo $response . '</br>';
return json_decode($response, true);;
}
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response

{
    "UUID": "9653fcbe-00e5-4c01-84d7-6ce429d9bca1",
    "Email": "test@test.com",
    "FirstName": "test",
    "LastName": "test",
    "Position": "test",
    "PhoneNumber": "98765432123",
    "MobilePhone": "8179186432",
    "Status": "ACTIVE"
}

 

Retrieve partner users

Overview

Use the getPartnerUser API method in Channel Manager to retrieve users for a specific partner.

   This API method is available only on API version 6.0.

Request parameters

Parameter name Type Required/Optional Description
uuid String Required Partner unique identifier.
email String Required Email of the partner-user.
sessionID String Required Output of the Login method.

Request example

<?php

declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'getPartnerUser';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "PartnerUserUUID" : "95fbb26a-43d6-482a-8544-d07f942aec8d", 
    "Email":"test@test.com"
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object
    {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }

        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        
        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url . '?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
       // $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Response

{
    "UUID": "9653fcbe-00e5-4c01-84d7-6ce429d9bca1",
    "Email": "test@test.com",
    "FirstName": "test",
    "LastName": "test",
    "Position": "test",
    "PhoneNumber": "98765432123",
    "MobilePhone": "8179186432",
    "Status": "ACTIVE"
}

 

Delete partner user

Overview

Use the deletePartnerUser method via JSON-RPC API 6.0 to delete a partner user. 

Required parameters

Parameter  Type Required/Optional Description
sessionID String Required Output of the Login method.
UUID String Required Partner unique identifier.
partnerUserUUID String Required Partner user unique identifier.

Request sample

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/rpc/6.0';
    public const ACTION = 'deletePartnerUser';
    public const ADDITIONAL_OPTIONS = null;
    public const PARTNER_UUID = '95b6b8bd-20db-478a-9682-d165f5d85d46';
    public const PARTNER_USER_UUID = '95c329d6-b45d-44ea-856a-1af254d06ae9';
    //array or JSON
    public const PAYLOAD =  <<<JSON
{}
JSON;
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
        return compact('merchantCode', 'date', 'hash');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }

        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, Configuration::PARTNER_UUID, Configuration::PARTNER_USER_UUID, $payload];
        }
        $payload = array_filter($payload);

        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);

        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response

Boolean True or false.

Update partner user

Overview

Use the updatePartnerUser method via JSON-RPC API 6.0 to update a partner user. 

Required parameters

Parameter  Type Required/Optional Description
sessionID String Required Output of the Login method.
UUID String Required Partner unique identifier.
partnerUserUUID String Required Partner user unique identifier.

Request sample

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/rpc/6.0';
    public const ACTION = 'updatePartnerUser';
    public const ADDITIONAL_OPTIONS = null;
    public const PARTNER_UUID = '95b6b8bd-20db-478a-9682-d165f5d85d46';
    public const PARTNER_USER_UUID = '95c329d6-b45d-44ea-856a-1af254d06ae9';
    //array or JSON
    public const PAYLOAD = <<<JSON
{  
    "Email": "test@test.com",
    "FirstName": "test", 
    "LastName": "test",  
    "Position": "test",  
    "PhoneNumber": "98765432123", 
    "MobilePhone": "8179186432",
    "Status": "ACTIVE" 
}
JSON;
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
        return compact('merchantCode', 'date', 'hash');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }

        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, Configuration::PARTNER_UUID, Configuration::PARTNER_USER_UUID, $payload];
        }
        $payload = array_filter($payload);

        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);

        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response

{
    "UUID": "95d59280-3b7d-4d5b-8b9f-7b66fe900045",
    "Email": test@test.com,
    "FirstName": "test2",
    "LastName": "test2",
    "Position": "test2",
    "PhoneNumber": "98765432123",
    "MobilePhone": null,
    "Status": "ACTIVE"
}

 

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo