November 8, 2022

API Reference

Public parameters

Request URL
Request Path parameter
parametersmusttypelengthdesc
mchidYesstring32#
appidYesstring32#

example

>https://baseUrl/v3/2020/pay/MCH20201/APP100

Method

>POST

>Content-type: application/x-www-form-urlencoded; charset=UTF-8

Signature string
payment signature

>SHA1(action_type+out_trade_no+amt+currency+ip+nonce_str+key)

retrieve signature

>SHA1(action_type+out_trade_no+nonce_str+key)

refund signature

>SHA1(action_type+txid+refund_amt+refund_reason+nonce_str+key)

Request Parameters

Payment parameters
parametersmusttypelengthdesc
action_typeYesstring10PAY
out_trade_noYesstring255order no
amtYesstring12,2transaction amount
currencyYesstring3transaction currency
ipYesstring255#
nonce_strYesstring1616 characters or fewer or fewer. For more information
signYesstring255Please see the Signature string
card.numYesstring255#
card.yearYesstring4#
card.monthYesstring2#
card.cvvYesstring4#
customer.first_nameYesstring255#
customer.last_nameYesstring255#
customer.countryYesstring2Please see the Country Code
customer.stateYesstring255#
customer.cityYesstring255#
customer.addressYesstring255#
customer.postcodeYesstring255#
customer.emailYesstring255#
customer.mobileYesstring255#
shipping.first_nameYesstring255#
shipping.last_nameYesstring255#
shipping.countryYesstring2Please see the Country Code
shipping.stateYesstring255#
shipping.cityYesstring255#
shipping.addressYesstring255#
shipping.postcodeYesstring255#
shipping.emailYesstring255#
shipping.mobileYesstring255#
goods[0].nameYesstring255goods name
goods[0].quantityYesstring9goods quantity
goods[0].priceYesstring12,2goods price
Example
<?php
$request = new HttpRequest();
$request->setUrl('https://baseUrl/v3/2020/pay/MCH20201/APP100');
$request->setMethod(HTTP_METH_POST);
$request->setContentType('application/x-www-form-urlencoded');
$request->setPostFields([
  'out_trade_no' => '4086d438-f2b1-eb59-7943',
  'amt' => '1111.00',
  'currency' => 'USD',
  'ip' => '1.1.1.1',
  'nonce_str' => '58k5EZTmB5ZnSTPn',
  'sign' => '40b00f6898f66ee74d1d12a8228019f00508665a',
  'card.num' => '4242424242424242',
  'card.year' => '2023',
  'card.month' => '12',
  'card.cvv' => '123',
  'customer.first_name' => 'Alex',
  'customer.last_name' => 'Bob',
  'customer.country' => 'US',
  'customer.state' => 'NY',
  'customer.city' => 'New York',
  'customer.address' => 'Address 123',
  'customer.postcode' => '313222',
  'customer.email' => 'alexander.aloha@gmail.com',
  'customer.mobile' => '45671345',
  'shipping.first_name' => 'Alex',
  'shipping.last_name' => 'Bob',
  'shipping.country' => 'US',
  'shipping.state' => 'NY',
  'shipping.city' => 'New York',
  'shipping.address' => 'Address 123',
  'shipping.postcode' => '313222',
  'shipping.email' => 'alexander.aloha@gmail.com',
  'shipping.mobile' => '66668888',
  'goods[0].name' => 'cap',
  'goods[0].quantity' => '1',
  'goods[0].price' => '100.00',
  'action_type' => 'PAY'
]);
try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
Payment Response example
    {
        "out_trade_no": "acb5c930-5a77-74a6-48d0",
        "txid": "S1578594295660978176",
        "amt": "100.00",
        "ccy": "USD",
        "code": "0000",
        "msg": "Payment Success",
        "bill": "globalmerchant.solutions"
    }
Payment Response parameter
parametersmusttypedesc
out_trade_noYesstring#
txidYesstring#
amtYesstring#
ccyYesstring#
codeYesstring#
msgYesstring#
billYesstring#
Retrieve parameters
parametersmusttypelengthdesc
action_typeYesstring10RETRIEVE
out_trade_noYesstring255#
nonce_strYesstring255#
signYesstring255#
Example
<?php
$request = new HttpRequest();
$request->setUrl('https://baseUrl/v3/2020/pay/MCH20201/APP100');
$request->setMethod(HTTP_METH_POST);
$request->setContentType('application/x-www-form-urlencoded');
$request->setPostFields([
  'out_trade_no' => '4086d438-f2b1-eb59-7943',
  'nonce_str' => '58k5EZTmB5ZnSTPn',
  'sign' => '40b00f6898f66ee74d1d12a8228019f00508665a',
  'action_type' => 'RETRIEVE'
]);
try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
Retrieve Response example
{
    "out_trade_no": "2f9876bb-ee66-2de3-4ef4",
    "txid": "S1578617547481456640",
    "amt": "100.00",
    "ccy": "USD",
    "code": "0000",
    "msg": "Payment Success"
}
Retrieve Response parameter
parametersmusttypedesc
out_trade_noYesstring#
txidYesstring#
amtYesstring#
ccyYesstring#
codeYesstring#
msgYesstring#
Refund parameters
parametersmusttypelengthdesc
action_typeYesstring10REFUND
txidYesstring255#
refund_amtYesstring12,2#
refund_reasonYesstring255#
nonce_strYesstring255#
signYesstring255#
Example
<?php
$request = new HttpRequest();
$request->setUrl('https://baseUrl/v3/2020/pay/MCH20201/APP100');
$request->setMethod(HTTP_METH_POST);
$request->setContentType('application/x-www-form-urlencoded');
$request->setPostFields([
  'nonce_str' => '58k5EZTmB5ZnSTPn',
  'sign' => '40b00f6898f66ee74d1d12a8228019f00508665a',
  'action_type' => 'REFUND',
  'txid' => 'S1578568969333547008',
  'refund_amt' => '100.00',
  'refund_reason' => 'test'
]);
try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
Refund Response example
{
    "out_trade_no": "b2948e87-3b4b-8774-7aa3",
    "txid": "S1578568969333547008",
    "code": "2007",
    "msg": "Refund apply success"
}
Refund Response parameter
parametersmusttypedesc
out_trade_noYesstring#
txidYesstring#
codeYesstring#
msgYesstring#

Appendix

Country Code

CountryCode
AfghanistanAF
ÅlandIslandsAX
AlbaniaAL
AlgeriaDZ
AmericanSamoaAS
AndorraAD
AngolaAO
AnguillaAI
AntarcticaAQ
AntiguaandBarbudaAG
ArgentinaAR
ArmeniaAM
ArubaAW
AustraliaAU
AustriaAT
AzerbaijanAZ
BahamasBS
BahrainBH
BangladeshBD
BarbadosBB
BelarusBY
BelgiumBE
BelizeBZ
BeninBJ
BermudaBM
BhutanBT
Bolivia(PlurinationalStateof)BO
Bonaire,SintEustatiusandSaba[d]BQ
BosniaandHerzegovinaBA
BotswanaBW
BouvetIslandBV
BrazilBR
BritishIndianOceanTerritoryIO
BruneiDarussalamBN
BulgariaBG
BurkinaFasoBF
BurundiBI
CaboVerdeCV
CambodiaKH
CameroonCM
CanadaCA
CaymanIslandsKY
CentralAfricanRepublicCF
ChadTD
ChileCL
ChinaCN
ChristmasIslandCX
Cocos(Keeling)IslandsCC
ColombiaCO
ComorosKM
CongoCG
Congo,DemocraticRepublicoftheCD
CookIslandsCK
CostaRicaCR
Côted’IvoireCI
CroatiaHR
CubaCU
CuraçaoCW
CyprusCY
CzechiaCZ
DenmarkDK
DjiboutiDJ
DominicaDM
DominicanRepublicDO
EcuadorEC
EgyptEG
ElSalvadorSV
EquatorialGuineaGQ
EritreaER
EstoniaEE
EswatiniSZ
EthiopiaET
FalklandIslands(Malvinas)FK
FaroeIslandsFO
FijiFJ
FinlandFI
FranceFR
FrenchGuianaGF
FrenchPolynesiaPF
FrenchSouthernTerritoriesTF
GabonGA
GambiaGM
GeorgiaGE
GermanyDE
GhanaGH
GibraltarGI
GreeceGR
GreenlandGL
GrenadaGD
GuadeloupeGP
GuamGU
GuatemalaGT
GuernseyGG
GuineaGN
Guinea-BissauGW
GuyanaGY
HaitiHT
HeardIslandandMcDonaldIslandsHM
HolySeeVA
HondurasHN
HongKongHK
HungaryHU
IcelandIS
IndiaIN
IndonesiaID
Iran(IslamicRepublicof)IR
IraqIQ
IrelandIE
IsleofManIM
IsraelIL
ItalyIT
JamaicaJM
JapanJP
JerseyJE
JordanJO
KazakhstanKZ
KenyaKE
KiribatiKI
Korea(DemocraticPeople’sRepublicof)KP
Korea,RepublicofKR
KuwaitKW
KyrgyzstanKG
LaoPeople’sDemocraticRepublicLA
LatviaLV
LebanonLB
LesothoLS
LiberiaLR
LibyaLY
LiechtensteinLI
LithuaniaLT
LuxembourgLU
MacaoMO
MadagascarMG
MalawiMW
MalaysiaMY
MaldivesMV
MaliML
MaltaMT
MarshallIslandsMH
MartiniqueMQ
MauritaniaMR
MauritiusMU
MayotteYT
MexicoMX
Micronesia(FederatedStatesof)FM
Moldova,RepublicofMD
MonacoMC
MongoliaMN
MontenegroME
MontserratMS
MoroccoMA
MozambiqueMZ
MyanmarMM
NamibiaNA
NauruNR
NepalNP
NetherlandsNL
NewCaledoniaNC
NewZealandNZ
NicaraguaNI
NigerNE
NigeriaNG
NiueNU
NorfolkIslandNF
NorthMacedoniaMK
NorthernMarianaIslandsMP
NorwayNO
OmanOM
PakistanPK
PalauPW
Palestine,StateofPS
PanamaPA
PapuaNewGuineaPG
ParaguayPY
PeruPE
PhilippinesPH
PitcairnPN
PolandPL
PortugalPT
PuertoRicoPR
QatarQA
RéunionRE
RomaniaRO
RussianFederationRU
RwandaRW
SaintBarthélemyBL
SaintHelena,AscensionandTristandaCunha[e]SH
SaintKittsandNevisKN
SaintLuciaLC
SaintMartin(Frenchpart)MF
SaintPierreandMiquelonPM
SaintVincentandtheGrenadinesVC
SamoaWS
SanMarinoSM
SaoTomeandPrincipeST
SaudiArabiaSA
SenegalSN
SerbiaRS
SeychellesSC
SierraLeoneSL
SingaporeSG
SintMaarten(Dutchpart)SX
SlovakiaSK
SloveniaSI
SolomonIslandsSB
SomaliaSO
SouthAfricaZA
SouthGeorgiaandtheSouthSandwichIslandsGS
SouthSudanSS
SpainES
SriLankaLK
SudanSD
SurinameSR
SvalbardandJanMayen[f]SJ
SwedenSE
SwitzerlandCH
SyrianArabRepublicSY
Taiwan,ProvinceofChinaTW
TajikistanTJ
Tanzania,UnitedRepublicofTZ
ThailandTH
Timor-LesteTL
TogoTG
TokelauTK
TongaTO
TrinidadandTobagoTT
TunisiaTN
TurkeyTR
TurkmenistanTM
TurksandCaicosIslandsTC
TuvaluTV
UgandaUG
UkraineUA
UnitedArabEmiratesAE
UnitedKingdomofGreatBritainandNorthernIrelandGB
UnitedStatesofAmericaUS
UnitedStatesMinorOutlyingIslands[h]UM
UruguayUY
UzbekistanUZ
VanuatuVU
Venezuela(BolivarianRepublicof)VE
VietNamVN
VirginIslands(British)VG
VirginIslands(U.S.)VI
WallisandFutunaWF
WesternSaharaEH
YemenYE
ZambiaZM
ZimbabweZW