Create a customer account
\nThe /create endpoint is where you create customer profiles on the PingPong platform.
To provide access to the PingPong platform's functionality, you must first create an account for each customer.
\n\n\nNote: You cannot receive or payout funds for your customer without creating an account for them.
\n
PingPong will provide a unique ID for each of your customers (merchant_id), which must be used for all subsequent operations.
๐ฌ Request
\n๐๏ธ Sample payload
\n{\n \"email\": \"abc@clientname.com\",\n \"phone_no\": \"4162738066\",\n \"phone_prefix\": \"+86\",\n \"partner_user_id\": \"ClientCustomerID1234\"\n}\n\n๐ค Response
\n","urlObject":{"path":["v2","currentz","merchant","create"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"d32d02d2-92d8-4975-91ad-ca7f20a8c6d3"},{"name":"Query customer account","event":[{"listen":"test","script":{"id":"56e7a323-c796-43f8-bfae-5373cae7ad8a","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"type":"text/javascript"}}],"id":"27dbe089-decb-44b1-a8ce-33e6088bec8d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"partner_user_id\": \"Query customer account
\nUse the customer ID on your platform to look up the customer ID on the PingPong platform (the merchant_id returned when you create a customer account).
๐ฌ Request
\n๐ค Response
\n","urlObject":{"path":["v2","currentz","merchant","query"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"27dbe089-decb-44b1-a8ce-33e6088bec8d"},{"name":"Upload files","event":[{"listen":"test","script":{"id":"fc99a097-8013-4564-ba39-1c10f555f7e0","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"type":"text/javascript","packages":{}}}],"id":"e5f0054f-4516-4c3a-989d-1c70053d4972","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"{{access_token}}","type":"text"},{"key":"Content-Type","value":"multipart/form-data","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"file","type":"file","src":"/Users/tanzz/Downloads/mysql-logo.png"}]},"url":"{{base_url}}/v3/currentz/file/upload","description":"Upload files
\nThe /upload endpoint is where you securely upload files to send to PingPong, including KYC and KYB documentation to support customer verification.
In the header, include multipart/form-data for content-type.
๐ฌ Request
\n๐ค Response
\n","urlObject":{"path":["v3","currentz","file","upload"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"e5f0054f-4516-4c3a-989d-1c70053d4972"},{"name":"Submit customer KYC","event":[{"listen":"test","script":{"id":"35fed3d2-3d12-41c8-b301-7450e887a4f0","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"type":"text/javascript","packages":{}}}],"id":"6c6b04e7-23b8-4fde-9f37-89d7cb3393e3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"{{access_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"location\": \"Submit customer KYC
\nThe /certification endpoint is where you submit information to verify customers or update their existing KYC information.
PingPong's KYC (Know Your Customer) checks
\nPayment industry regulations require that PingPong verifies your customers before you can process payments, pay out their funds, or offer financial products to them. These verification checks are commonly called Know Your Customer (KYC) checks.
\nBefore you can complete the customer's onboarding, you will need to create a PingPong Account for your customer, as you will need to reference the unique merchant_id that is returned when you create a customer account.
Check here for the KYC requirements. The file_id can be obtained by using Upload files to upload KYC materials.
KYC status
\nOnboarding is only complete once you submit your customer's KYC details and documentation and receive an APPROVED kyc_status via the KYC status webhook.
Note that verification requirements will differ depending on your platform's and customers' locations.
\nIf the customer details change or additional information is required, KYC can be resubmitted so long as the status is not already PENDING.
- \n
\nPENDINGย - Under review - this status is provided when the KYC review is incomplete. \n
\nAPPROVEDย - This status typically means your customer is fully compliant and ready to transact. \n
\nDECLINEDย - Review has either been rejected or further information has been requested by our Compliance team (RFI) to complete their review. Reason details will be provided, including any further information requested. \n
\n\nNote: Please be aware that requests for information (RFI) are for now included in the \"DECLINED\" KYC status and may not always indicate a rejection. Our approach to representing RFIs is currently being improved.
\n
๐ฌ Request
\n๐๏ธ Sample request for business, using company as an example
\n{\n \"merchant_id\": \"M2024121314005491902\",\n \"merchant_type\": \"enterprise\",\n \"location\": \"DE\",\n \"merchant_ack\": \"YES\",\n \"company\": {\n \"enterprise\": {\n \"business_type\": \"COMPANY\",\n \"name\": \"Pingpong\",\n \"name_in_local_lan\": \"Pingpong\",\n \"business_certificate_no\": \"DE123456789\",\n \"certificate_of_registration\": \"N1234567891011121314151617\",\n \"establishment_date\": \"2019-02-13\",\n \"expiry_date\": \"2099-02-13\",\n \"tax_id_type\": \"VAT\",\n \"tax_id_number\": \"tax_id_number1111\",\n \"province\": \"Raสผs al Khaymah\",\n \"city\": \"Ras Al Khaimah\",\n \"district\": \"district1111\",\n \"street_address\": \"Schillerstraรe 23\",\n \"postcode\": \"999077\",\n \"products_and_services_category\": \"KC02001008\",\n \"account_usage\": [\"ONLINE_MARKETPLACE_TRADING\", \"PAY_SUPPLIERS\"],\n \"article_of_association\": \"N1234567891011121314151621\",\n \"share_structure\": \"N1234567891011121314151620\",\n \"business_proof_description\": \"Selling products or purchasing raw materials on online platforms\",\n \"business_proof_url\": \"http://www.baidu.com\",\n \"business_proof_screenshot\": \"N1234567891011121314151622\",\n \"trade_type\": \"\",\n \"export_country\": \"CN\",\n \"supplementary_information\": \"supplementary information\",\n \"supplementary_materials\": [\"N1234567891011121314151619\", \"N1234567891011121314151630\"]\n },\n \"business_person\": [{\n \"role_type\": \"AGENT_OR_AUTHORISED_PERSON\",\n \"id_type\": \"PASSPORT\",\n \"street_address\": \"ๅๅท็ๆ้ฝๅธ้ฆๆฑๅบๆฅ็่ทฏ11ๅท\",\n \"country\": \"CN\",\n \"id_number\": \"510303197503012345\",\n \"gender\": \"MALE\",\n \"city\": \"ๆ้ฝๅธ\",\n \"id_expiry_date\": \"2039-05-20\",\n \"date_of_birth\": \"1975-03-07\",\n \"postcode\": \"610001\",\n \"province_of_birth\": \"ๅๅท็\",\n \"province\": \"ๅๅท็\",\n \"supplementary_materials\": [\"N1234567891011121314151622\"],\n \"country_of_birth\": \"1974-11-02\",\n \"nationality\": \"CN\",\n \"id_doc_back\": \"N1234567891011121314151623\",\n \"id_doc_front\": \"N1234567891011121314151624\",\n \"id_issue_date\": \"2009-05-20\",\n \"supplementary_information\": \"supplementary_information11111\",\n \"first_name\": \"Hongbo\",\n \"middle_name\": \"\",\n \"last_name\": \"Lin\",\n \"first_name_in_local_lan\": \"first name in local language\",\n \"middle_name_in_local_lan\": \"middle name in local language\",\n \"last_name_in_local_lan\": \"last name in local language\",\n \"district\": \"district11\",\n \"proof_of_address\": \"N1234567891011121314151625\"\n },\n {\n \"role_type\": \"UBO\",\n \"id_type\": \"PASSPORT\",\n \"street_address\": \"ๅๅท็ๆ้ฝๅธ้ฆๆฑๅบๆฅ็่ทฏ55ๅท\",\n \"country\": \"CN\",\n \"gender\": \"FEMALE\",\n \"city\": \"ๆ้ฝๅธ\",\n \"date_of_birth\": \"1979-11-01\",\n \"province_of_birth\": \"ๅๅท็\",\n \"province\": \"ๅๅท็\",\n \"supplementary_materials\": [\"N1234567891012345678910\"],\n \"country_of_birth\": \"1979-11-02\",\n \"first_name\": \"Lin\",\n \"id_number\": \"1234567891011121314\",\n \"share_proportion\": \"34\",\n \"id_expiry_date\": \"2038-03-01\",\n \"postcode\": \"610000\",\n \"last_name\": \"Hongli\",\n \"middle_name\": \"\",\n \"nationality\": \"CN\",\n \"first_name_in_local_lan\": \"first_name_in_local_lan11\",\n \"middle_name_in_local_lan\": \"middle_name_in_local_lan11\",\n \"id_doc_back\": \"N1234567891011121314151624\",\n \"id_doc_front\": \"N1234567891011121314151628\",\n \"district\": \"district11\",\n \"id_issue_date\": \"2009-05-20\",\n \"supplementary_information\": \"supplementary_information11111\",\n \"last_name_in_local_lan\": \"last_name_in_local_lan11\",\n \"proof_of_address\": \"N1234567891011121314151629\"\n },\n {\n \"role_type\": \"UBO\",\n \"id_type\": \"PASSPORT\",\n \"street_address\": \"ๅๅท็ๆ้ฝๅธ้ฆๆฑๅบๆฅ็่ทฏ56ๅท\",\n \"country\": \"HK\",\n \"gender\": \"MALE\",\n \"city\": \"Ras Al Khaimah\",\n \"date_of_birth\": \"1959-11-01\",\n \"province_of_birth\": \"Abu Dhabi\",\n \"province\": \"Ajman\",\n \"supplementary_materials\": [\"N1234567891011121314151620\"],\n \"country_of_birth\": \"1969-11-02\",\n \"first_name\": \"DEFirstName\",\n \"id_number\": \"DEid_number123456\",\n \"share_proportion\": \"54\",\n \"id_expiry_date\": \"2048-03-01\",\n \"postcode\": \"610010\",\n \"last_name\": \"DELastName\",\n \"middle_name\": \"\",\n \"nationality\": \"HK\",\n \"first_name_in_local_lan\": \"first_name_in_local_lan11\",\n \"middle_name_in_local_lan\": \"middle_name_in_local_lan11\",\n \"id_doc_back\": \"N301701202418198094282753\",\n \"id_doc_front\": \"N301701202418193799315457\",\n \"district\": \"district11\",\n \"id_issue_date\": \"2009-05-20\",\n \"supplementary_information\": \"supplementary_information11111\",\n \"last_name_in_local_lan\": \"last_name_in_local_lan11\",\n \"proof_of_address\": \"N301701203083419808956417\"\n },\n {\n \"role_type\": \"DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP\",\n \"id_type\": \"PASSPORT\",\n \"street_address\": \"Schillerstraรe 24\",\n \"country\": \"AU\",\n \"gender\": \"MALE\",\n \"city\": \"Berlin\",\n \"date_of_birth\": \"1974-11-01\",\n \"province_of_birth\": \"1975-11-01\",\n \"province\": \"Berlin\",\n \"supplementary_materials\": [\"N301701203083419808956417\"],\n \"country_of_birth\": \"1976-11-01\",\n \"first_name\": \"DEFirstName\",\n \"id_number\": \"DEid_number098879\",\n \"id_expiry_date\": \"2048-03-01\",\n \"postcode\": \"610012\",\n \"last_name\": \"DELastName\",\n \"middle_name\": \"DEMiddle_name11\",\n \"nationality\": \"AU\",\n \"first_name_in_local_lan\": \"DEFirstName_local_lan\",\n \"middle_name_in_local_lan\": \"DEMiddle_name11_local_lan\",\n \"id_doc_back\": \"N301701202418391367811073\",\n \"id_doc_front\": \"N301701202418387072843777\",\n \"id_issue_date\": \"2019-05-20\",\n \"supplementary_information\": \"supplementary_information11111\",\n \"last_name_in_local_lan\": \"DELastName_local_lan\",\n \"district\": \"district111\",\n \"proof_of_address\": \"N301701203083419808956417\"\n }\n ]\n }\n}\n\n๐๏ธ Sample request for individual
\n{\n \"location\": \"DE\",\n \"merchant_id\": \"M2024121314005491901\",\n \"merchant_type\": \"individual\",\n \"merchant_ack\": \"YES\",\n \"customer\": {\n \"first_name\": \"LEUNG DE\",\n \"middle_name\": \"LEUNGMohammed\",\n \"last_name\": \"WINGPO DE\",\n \"first_name_in_local_lan\": \"Ahmed\",\n \"middle_name_in_local_lan\": \"Mohammed\",\n \"last_name_in_local_lan\": \"Al Maktoum\"\n \"id_type\": \"PASSPORT\",\n \"id_number\": \"YDE123456789101213\",\n \"id_issue_date\": \"2019-11-06\",\n \"id_expiry_date\": \"9999-12-31\",\n \"nationality\": \"DE\",\n \"gender\": \"FEMALE\",\n \"province\": \"Frankfurt am Main province\",\n \"city\": \"Frankfurt am Main\",\n \"district\": \"Municipality\",\n \"street_address\": \"Musterstraรe 17\",\n \"postcode\": \"999088\",\n \"proof_of_address\": \"N123456789109808956417\",\n \"date_of_birth\": \"1997-09-06\",\n \"province_of_birth\": \"province_of_birth Fujairah\",\n \"country_of_birth\": \"DE\",\n \"products_and_services_category\": \"KC02001028\",\n \"account_usage\": [\"ONLINE_MARKETPLACE_TRADING\"],\n \"business_proof_description\": \"selling sports clothes and shoes online\",\n \"business_proof_url\": \"http://www.baidu.com\",\n \"business_proof_screenshot\": \"N123456789109808956421\",\n \"id_doc_back\": \"N123456789109808956419\",\n \"id_doc_front\": \"N123456789109808956420\",\n \"supplementary_information\": \"supplementary_information11111\"\n \"supplementary_materials\": [\"N123456789109808956419\"],\n }\n}\n\n๐ค Response
\n๐๏ธ Sample response for business
\n{\n \"kyc_status\": \"PENDING\",\n \"kyc_submit_status\": \"PENDING\",\n \"liveness\": [\n {\n \"role_type\": \"PARTNER\",\n \"min_liveness_count\": 1,\n \"scope\": [\n {\n \"first_name\": \"Wayne\",\n \"middle_name\": \"\",\n \"last_name\": \"Chen\",\n \"verify_url\": \"http://www.pingpongx.com\"\n },\n {\n \"first_name\": \"John\",\n \"middle_name\": \"\",\n \"last_name\": \"Doe\",\n \"verify_url\": \"http://www.pingpongx.com\"\n }\n ]\n },\n {\n \"role_type\": \"AGENT_OR_AUTHORISED_PERSON\",\n \"min_liveness_count\": 1,\n \"scope\": [\n {\n \"first_name\": \"Alice\",\n \"middle_name\": \"Mary\",\n \"last_name\": \"Robinson\",\n \"verify_url\": \"http://www.pingpongx.com\"\n }\n ]\n },\n {\n \"role_type\": \"UBO\",\n \"min_liveness_count\": 2,\n \"scope\": [\n {\n \"first_name\": \"Jack\",\n \"middle_name\": \"Captain\",\n \"last_name\": \"Sparrow\",\n \"verify_url\": \"http://www.pingpongx.com\",\n },\n {\n \"first_name\": \"ไธ\",\n \"middle_name\": \"\",\n \"last_name\": \"ๅผ \",\n \"verify_url\": \"http://www.pingpongx.com\",\n },\n {\n \"first_name\": \"Tai Man\",\n \"middle_name\": \"\",\n \"last_name\": \"Chan\",\n \"verify_url\": \"http://www.pingpongx.com\",\n }\n ]\n }\n\n๐๏ธ Sample response for individual
\n{\n \"kyc_status\": \"PENDING\",\n \"kyc_submit_status\": \"PENDING\",\n \"liveness\": [\n {\n \"min_liveness_count\": 1,\n \"scope\": [\n {\n \"first_name\": \"Alyssa\",\n \"middle_name\": \"\",\n \"last_name\": \"WU\",\n \"verify_url\": \"http://www.pingpongx.com\",\n }\n ]\n }\n ]\n}\n\nQuery KYC status
\nCheck the status of your customer's KYC review using the merchant_id returned when you create a customer account.
Only customers with an APPROVED status will be able to transact.
- \n
\nPENDING- Under review - this status is provided when the KYC review is incomplete. \n
\nAPPROVED- This status typically means your customer is fully compliant and ready to transact. \n
\nDECLINED- Review has either been rejected or further information has been requested by our Compliance team (RFI) to complete their review. Reason details will be provided, including any further information requested. \n
\n\nNote: Please be aware that requests for information (RFI) are for now included in the \"DECLINED\" KYC status and may not always indicate a rejection. Our approach to representing RFIs is currently being improved.
\n
๐ฌ Request
\n๐ค Response
\n๐๏ธ Sample response for business
\n{\n \"kyc_status\": \"PENDING\",\n \"kyc_submit_status\": \"PENDING\",\n \"reason\": \"\",\n \"liveness\": [\n {\n \"role_type\": \"PARTNER\",\n \"min_liveness_count\": 1,\n \"scope\": [\n {\n \"first_name\": \"Adam\",\n \"middle_name\": \"\",\n \"last_name\": \"Smith\",\n \"verify_url\": \"http://www.pingpongx.com\"\n },\n {\n \"first_name\": \"John\",\n \"middle_name\": \"\",\n \"last_name\": \"Doe\",\n \"verify_url\": \"http://www.pingpongx.com\"\n }\n ]\n },\n {\n \"role_type\": \"AGENT_OR_AUTHORISED_PERSON\",\n \"min_liveness_count\": 1,\n \"scope\": [\n {\n \"first_name\": \"Alice\",\n \"middle_name\": \"Mary\",\n \"last_name\": \"Robinson\",\n \"verify_url\": \"http://www.pingpongx.com\"\n }\n ]\n },\n {\n \"role_type\": \"UBO\",\n \"min_liveness_count\": 2,\n \"scope\": [\n {\n \"first_name\": \"Jack\",\n \"middle_name\": \"Captain\",\n \"last_name\": \"Sparrow\",\n \"verify_url\": \"http://www.pingpongx.com\",\n },\n {\n \"first_name\": \"ไธ\",\n \"middle_name\": \"\",\n \"last_name\": \"ๅผ \",\n \"verify_url\": \"http://www.pingpongx.com\",\n },\n {\n \"first_name\": \"Tai Man\",\n \"middle_name\": \"\",\n \"last_name\": \"Chan\",\n \"verify_url\": \"http://www.pingpongx.com\",\n }\n ]\n }\n\n๐๏ธ Sample response for individual
\n{\n \"kyc_status\": \"PENDING\",\n \"kyc_submit_status\": \"PENDING\",\n \"reason\": \"\",\n \"liveness\": [\n {\n \"min_liveness_count\": 1,\n \"scope\": [\n {\n \"first_name\": \"Alyssa\",\n \"middle_name\": \"\",\n \"last_name\": \"Wu\",\n \"verify_url\": \"http://www.pingpongx.com\",\n }\n ]\n }\n ]\n}\n\nInforming your users about their KYC review status
\nIncrease conversions by informing your customers of the KYC status updates sent by PingPong.
\n- \n
\nPENDING- Under review - this status is provided when the KYC review is incomplete. \n
\nAPPROVED- This status typically means your customer is fully compliant and ready to transact. \n
\nDECLINED- Review rejected. Our compliance team has rejected this customer;reasondetails are provided. \n
These statuses are subject to change.
\n","urlObject":{"path":["v3","currentz","merchant","certification","query"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"05964afc-a130-4d91-8d4f-23546f1692ba"},{"name":"webhook KYC status","id":"b9579db4-ac00-4e14-a42c-bbda5d036e54","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"type":"default","value":"application/json; charset=utf-8","key":"Content-Type"},{"type":"default","value":"currents.kyc","key":"topic"}],"body":{"mode":"raw","raw":"{\n \"merchant_id\":\"๐ช KYC status webhook
\nThe currents.kyc webhook is where you listen for updates to your customers' KYC status.
PingPong will send a webhook with an updated KYC status once the KYC review is completed. Only customers with an APPROVED status will be able to transact.
Webhook: currents.kyc
\nInforming your users about their KYC review status
\nIncrease conversions by informing your customers of the KYC status updates sent by PingPong.
\n- \n
PENDING- Under review - this status is provided when the KYC review is incomplete. \nAPPROVED- This status typically means your customer is fully compliant and ready to transact. \nDECLINED- Review rejected. Our compliance team has rejected this customer;reasondetails are provided. \n
These statuses are subject to change.
\n","urlObject":{"protocol":"https","path":["webhook","pp"],"host":["customer","domain","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"b9579db4-ac00-4e14-a42c-bbda5d036e54"},{"name":"webhook liveness check result","id":"98fa5e29-6908-4e56-a140-c79b7cd8000b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json; charset=utf-8","type":"default"},{"key":"topic","value":"currents.kyc.check","type":"default"}],"body":{"mode":"raw","raw":"{\n \"merchant_id\": \"M2025021019013393595\",\n \"role_type\": \"DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP\",\n \"last_name\": \"WU\",\n \"middle_name\": \"\",\n \"first_name\": \"Alyssa\"\n \"liveness_check_result\": \"SUCCESS\"\n}"},"url":"https://customer.domain.com/webhook/pp","description":"๐ช Liveness check webhook
\nThe currents.kyc.check webhook is where you listen for updates to your customers' liveness check status.
PingPong will send a webhook with an updated liveness check status once the liveness check is completed.
\nWebhook: currents.kyc.check
\n","urlObject":{"protocol":"https","path":["webhook","pp"],"host":["customer","domain","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"98fa5e29-6908-4e56-a140-c79b7cd8000b"}],"id":"e6f163d0-49e6-417e-a094-ae712d6efc91","description":"This collection enables you to onboard your customers to the PingPong platform. You can create accounts for your customers, submit their KYC/ KYB details, and check their KYC status.
\n๐ How to onboard customers to the PingPong platform
\n๐ 4 simple steps to onboard your customers:
\nSTEP 1: Create a customer account:
\nThe /create endpoint is where you create customer profiles on the PingPong platform. Create a customer account for your customer and obtain a unique Customer ID (merchant_ID).
STEP 2: Upload customer verification documents
\nThe /upload endpoint is where you upload files for the documentation required to support customer verification.
STEP 3: Submit customer KYC for verification
\nThe /certification endpoint is where you verify customers or update their existing KYC information. Submit customer KYC details.
STEP 4: Obtain KYC status
\nThe currents.kyc webhook lets you listen for updates to your customers' KYC status. Once the KYC review is completed, PingPong will send a webhook with an updated KYC status.
Alternatively, you can call Query KYC status to get the latest KYC status for a given customer.
\nOnly customers with a APPROVED status can transact.
Mapping customer IDs
\nAt any point, you can query a customer account using the customer ID on your platform to look up the equivalent customer ID on the PingPong platform (the merchant_id returned when you create a customer account).
PingPong uses SFTP to push Virtual Account Statement files.
\n- \n
- Files are pushed daily at 5:00 am with data from the previous day. \n
- Files are kept for six months. \n
- File will be stored at
/statement/YYYYMMDD/statement_yyyyMMdd_batchNumber.xlsx\n
Clients will need to provide a public key (format: starting with ssh-rsa) and outbound IP in order for PingPong to configure their SFTP account.
\n","_postman_id":"8d6cfc52-30d1-427d-a5bf-626c2b2330f9"},{"name":"Apply for a virtual account","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"id":"355b46b8-7d0a-4d78-a63b-d6d8df809817"}}],"id":"7a012605-f09c-4f72-acb7-aaa4fdb8c311","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"account_purpose\": \"Apply for a virtual account
\nClients can open virtual accounts for their customers or for their own internal treasury management.
\nOnce your customers have an APPROVED kyc_status, you can apply for a virtual account for each currency you would like them to be able to receive.
Your implementation's available currencies will need to be defined with your solution manager and documented in your configuration specification (see Get started).
\nSee the full list of all the available collection currencies for virtual accounts by bank location.
\nSpecify VA type in account_purpose
\n- \n
- Use VA type A if incoming payments are to be be credited to the account balance of a client or customer (
account_purpose=01,02,03,21,22,23,24,25,26,27,28). \n - Use VA type B if incoming payments are to be credited to a specific VA (
account_purpose=04,05,09,12,31,32,33,34,35,36,37,38). \n
๐ฌ Request
\n๐ Scene subaccount object
\n๐๏ธ Sample payload
\n{\n \"account_purpose\": \"03\",\n \"merchant_id\": \"Customer1234\",\n \"store_id\": \"Store1234\",\n \"currency\": \"USD\",\n \"bank_location\": \"US\",\n \"scene_subaccount\": {\n \"first_name\": \"Dan\",\n \"last_name\": \"Sing\",\n \"type\": \"OTHER\",\n \"payer_cert_type\": \"01\",\n \"payer_cert_name\": \"Tim Smith\",\n \"payer_cert_no\": \"1234567\",\n \"payer_cert_front\": \"file1234567\",\n \"payer_cert_back\": \"file1234568\"\n }\n}\n\n๐ค Response
\n","urlObject":{"path":["v2","currentz","account","apply"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"7a012605-f09c-4f72-acb7-aaa4fdb8c311"},{"name":"Query virtual account information","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"id":"52cbb8ff-f77b-467e-85f7-d079a64985f9"}}],"id":"06212c2d-4323-4148-9ff1-131a4a3ae9b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"biz_id\": \"Query virtual account information
\nCheck the status of virtual accounts using the biz_id returned when you apply for a virtual account. Only an account with an account_status of AVAILABLE can be used for collections.
๐ฌ Request
\n๐๏ธ Sample payload
\n{\n \"biz_id\": \"BizID1234\"\n}\n\n๐ค Response
\n","urlObject":{"path":["v2","currentz","account","query"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"06212c2d-4323-4148-9ff1-131a4a3ae9b5"},{"name":"webhook VA status","id":"57d36d1f-56ea-4b72-b4d1-7b2ee20c9056","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"default","value":"application/json; charset=utf-8","key":"Content-Type"},{"type":"default","value":"AC100E70000078C90000001612E82022","key":"msgId"},{"type":"default","value":"885407","key":"bizId"},{"type":"default","value":"currents.account","key":"topic"},{"type":"default","value":"A1O+NnjAOQzPBAAxhSgxldtU8XvnVOo4p/QXcH60Yy2hN5nZT0qnHwsDjxsRqJuF1wz+OHkOrerc34kT 7KaQHO2sxUDQ8Vx0UPxYl8YTgtAGxuXpUfL9oe7X5ZD4Ir5Z00ePpwW/K4rO8AH0/hFyhpRdzxebaKioNNn2hE vN76I=","key":"sign"}],"body":{"mode":"raw","raw":"{\n \"biz_id\":\"๐ชVA status webhook
\nThe currents.account webhook is where you listen for updates to the virtual account account_status.
Only an account with an account_status of AVAILABLE can be used for collections.
Webhook: currents.account
\n","urlObject":{"protocol":"https","path":["webhook","pp"],"host":["customer","domain","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"57d36d1f-56ea-4b72-b4d1-7b2ee20c9056"},{"name":"webhook pre_receive","id":"a7614d91-71a5-4127-83c1-2c75872e63bc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"type":"default","value":"application/json; charset=utf-8","key":"Content-Type"},{"type":"default","value":"currents.pre_receive","key":"topic"}],"body":{"mode":"raw","raw":"{\n \"merchant_id\":\"๐ชPre receive webhook
\nNotification of funds received. The currents.pre_receive webhook is where you listen for funds received by PingPong.
Webhook: currents.pre_receive
\n","urlObject":{"protocol":"https","path":["webhook","pp"],"host":["customer","domain","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"a7614d91-71a5-4127-83c1-2c75872e63bc"},{"name":"Refund collection","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"id":"be2e5a3f-30f3-4cd6-abf4-b796bb5fb2c1"}}],"id":"75e83e7d-7b2b-4d5d-9b1e-03dbfe220687","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"merchant_id\": \"Create refund
\nIf required, use this method to return funds that PingPong has received before they are credited to a customer or client's virtual account balance.
\n๐ฌ Request
\n๐ค Response
\n","urlObject":{"path":["v2","currentz","transaction","inbound","refund"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"75e83e7d-7b2b-4d5d-9b1e-03dbfe220687"},{"name":"webhook inbound","id":"62e8d716-141f-497f-9a2b-b13c5f2f380d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"type":"default","value":"application/json; charset=utf-8","key":"Content-Type"},{"type":"default","value":"currents.inbound","key":"topic"}],"body":{"mode":"raw","raw":"{\n \"merchant_id\":\"๐ช Inbound webhook
\nNotification of inbound B2B funds
\nThe currents.inbound webhook is where you listen for the status of inbound funds.
Webhook: currents.inbound
\nInforming your users about the inbound funds' review status
\n- \n
PENDING- Inbound funds have been submitted for review. \nAPPROVED- Inbound funds have been approved. \nCLOSED- Inbound funds have been rejected and may be resubmitted. \nREJECTED- If the inbound funds are rejected, the corresponding inbound flow cannot be initiated again. \nCANCELED- Inbound transaction has been cancelled. \nREFUNDED- Inbound funds have been rejected, and a refund has been made. \n
๐ Order contract information (contract_info_list array):
\nInforming your users about the trade order status
\n- \n
INITIAL- Contract order newly created \nAVAILABLE- Contract order in use \nCLOSED- Contract order has been closed \n
Query account balance
\nUse query account balance to obtain any of the following:
\n- \n
- the amounts held in all the client's accounts (leave
merchant_idandbiz_idnull) \n - the amounts held in all the accounts held by a customer (pass the
merchant_id) \n - the amount of funds held in a specific virtual account (pass the
biz_id) \n
Notes on account_type
\n- \n
- If the
account_type=BALANCE_ACCOUNT, theavail_amountreturned includes all funds that have been successfully credited to the account. \n - If the
account_type=TEMP_ACCOUNT, theavail_amountincludes all funds that have been received but have not yet been credited to the balance. \n
Notes on account_purpose
\n- \n
- If using VA type A, incoming payments will be credited to the account balance of a client or customer (
account_purpose=01,02,03,21,22,23,24,25,26,27,28) therefore, to query the balance of this type of account, there is no need to pass thebiz_idparameter. \n - If using VA type B, incoming payments will be credited to a specific VA so the
biz_idis required (account_purpose=04,05,09,12,31,32,33,34,35,36,37,38). \n
๐ฌ Request
\n๐๏ธ Sample payload
\n{\n \"merchant_id\": \"CustomerID1234\",\n \"account_type\": \"BALANCE_ACCOUNT\",\n \"currency\": \"GBP\",\n \"biz_id\": \"VA1234\"\n}\n\n๐ค Response
\n","urlObject":{"path":["v2","currentz","account","balance"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"0ccf1a8c-4bd6-47c1-ac76-e0f947be5928"},{"name":"Create a store","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"id":"ec680aa1-19e5-4785-8867-b4cac0db3056"}}],"id":"36d8ea4c-7d27-47c4-9326-39c558b9c451","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"merchant_id\": \"Create a store
\nSpecifically designed to serve the e-commerce vertical, this is where you create store profiles on the PingPong platform.
\nEach store represents a sales channel for the customer (merchant_id). If the store is to be created at the client level leave merchant_id = null.
๐ฌ Request
\n๐ Store object
\n๐ Scene self station object
\n๐ค Response
\n","urlObject":{"path":["v2","currentz","store","create"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"36d8ea4c-7d27-47c4-9326-39c558b9c451"},{"name":"Authorize a store","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"id":"0d40d10e-b4f6-4e3b-bf22-2cc77b3ebbbc"}}],"id":"fa275498-1f9e-4fff-a77f-e46c1fc9f6f5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"store_id\": \"Authorize a store
\nUse this request to connect the e-commerce platforms and marketplaces you need to collect funds from.
\n๐ฌ Request
\n๐ URL object
\n๐ Token object
\n๐ค Response
\n","urlObject":{"path":["v2","currentz","store","auth"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"fa275498-1f9e-4fff-a77f-e46c1fc9f6f5"}],"id":"25d577b0-d473-4049-b93e-a0f81513c012","description":"The /account endpoint is where you create virtual accounts for you and your customers to hold funds, and where you manage the collection of funds.
๐ How to enable customers to receive funds
\n๐ STEP 1: Apply for virtual accounts
\nOnce your customers have an APPROVED kyc_status, you can apply for a virtual account for each currency that you would like your customers to be able to receive. You will need to specify the customer's merchant_id.
\n\nE-commerce: If your implementation involves the collection of funds from e-commerce platforms or marketplaces, you will also need to create a store and use the returned
\nstore_idto authorise a store for each store you or your customers wish to recieve funds from.
๐ STEP 2: Query virtual account information
\nYou can check the status of virtual accounts and obtain account details to display to customers with query virtual account information. Alternatively, use the currents.account webhook to listen for updates to the virtual account account_status. Only an account with an account_status of AVAILABLE can be used for collections.
\n\nNote: If the
\naccount_purposeis 02 or 03, funds are always credited to the client or the customer (merchant_id); they can't be credited to a specific VA (biz_id).
๐ STEP 3: Listen for details of incoming funds to PingPong
\nThe currents.pre_receive webhook lets you listen for payer and recipient details for all incoming funds transaction_id to PingPong.
\n\nNote: If funds need to be returned to the payer, use the refund collection method to return funds before they are credited to a customer or client's virtual account balance.
\n
๐ STEP 4: Account balance update notifications
\nUse the currents.inbound webhook to listen for when the status of the fund review for a given transaction_id changes to APPROVED and the customer's virtual account balance can be updated.
๐ Reconciliation of balances
\nYou can use webhooks to monitor the amounts received and update your customers' account balances. To aid with reconciliation, you can also call Query account balance.
\nPingPong also uses SFTP to push daily Virtual Account Statement files.
\n๐ Virtual accounts for treasury management
\nIf you require virtual accounts in multiple currencies for internal treasury management, you can apply for a virtual account for each currency (simply leave the merchant_id blank).
Use the currents.inbound webhook to listen for the notification of funds received by PingPong.
Query exchange rate
\nThis method obtains an exchange rate, which can be used to exchange currencies between balances or when creating a payment.
\nThe method returns an fx object, which includes exchange details.
\n\nThe exchange rate (
\nfx.rate) is valid for 60 seconds.
There are two calculation options for an exchange, depending on whether you want to specify the amount to exchange in the origin currency or the amount you require in the target currency.
\n๐๏ธ Sample payload 1: Obtain the exact amount required in the target currency (DEFAULT)
\nFor example, exchange the required amount of EUR to obtain 500 USD. The amount is the target_currency amount.
{\n \"merchant_id\": \"Client1234\",\n \"origin_currency\": \"EUR\",\n \"target_currency\": \"USD\",\n \"amount\": \"500.00\",\n \"cal_rule\": \"TARGET2ORIGIN\",\n \"rate_type\": \"00\"\n}\n\n\n\nIf the
\ncal_ruleisNULL, the default is aTARGET2ORIGINcalculation.
๐๏ธ Sample payload 2: Specify the amount of the origin currency to be exchanged.
\nFor example, exchange 100 EUR for GBP. Theamount is the origin_currencyamount.
{\n \"merchant_id\": \"Client1234\",\n \"origin_currency\": \"EUR\",\n \"target_currency\": \"GBP\",\n \"amount\": \"100.00\",\n \"cal_rule\": \"ORIGIN2TARGET\",\n \"rate_type\": \"00\"\n}\n\n๐ฌ Request
\n๐ค Response
\n๐ FX object
\n๐ Order amount object
\n๐ Detail object
\n","urlObject":{"path":["v2","currentz","exchange","rate"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"37beb388-6352-4179-b8f7-a771c68a4996"},{"name":"Exchange currencies","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"resultCheck\", function () {"," //่ฏทๆฑๅ้็ปๆ้ช่ฏ"," pm.response.to.have.status(200);",""," //่ฟๅ็ปๆ้ช่ฏ"," var jsonData = pm.response.json();"," pm.expect(jsonData.code).to.eql(0);","});"],"id":"9f8ee10b-8f35-402b-a9e1-523fede28179"}}],"id":"63cef29a-b6e9-488d-9d57-a0302694b48a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"type":"text","value":"{{access_token}}","key":"Authorization"},{"type":"text","value":"application/json","key":"Content-Type"}],"body":{"mode":"raw","raw":"{\n \"amount\": \"Exchange currencies
\nExchange currencies by creating an FX transaction. To exchange currencies, you must first obtain the fx.rate_id which will be valid for 60 seconds with a query exchange rate.
\n\nNote on
\nCNYcurrency exchange. OnlyCNH(offshore RMB) currency exchange is currently supported. Although you can query theCNYexchange rate, actual currency exchange inCNYis not supported.
Target account
\nA specified VA will be credited if the biz_id is supplied. If the VA currency doesn't match the target_currency, an error is returned:
If the merchant_id is passed, the customer account will be credited. An error is returned if they don't have a VA in the target currency.
The client account will be credited if the merchant_id and biz_id are both null.
Calculation rules
\nThere are two cal_rule calculation options for an exchange, depending on whether you want to specify the amount to exchange in the origin currency or the amount you require in the target currency.
1: TARGET2ORIGIN or NULL to obtain the exact amount required in the target currency (DEFAULT)
\nFor example, exchange the required amount of EUR to obtain 500 USD. The amount is the target_currency amount.
2: ORIGIN2TARGET to specify the amount of the origin currency to be exchanged.
\nFor example, exchange 100 EUR for GBP. The amount is the origin_currency amount.
๐ฌ Request
\n๐๏ธ Sample payload
\n{\n \"amount\": \"500\",\n \"cal_rule\": \"ORIGIN2TARGET\",\n \"origin_currency\": \"EUR\",\n \"target_currency\": \"USD\",\n \"rate_id\": \"RateID1234\",\n \"partner_order_id\": \"PlatformOrder1234\",\n \"partner_user_id\": \"ClientXCustomer1234\",\n \"reference\": \"Testing\",\n \"from_account\": \"ACCOUNT_BALANCE\",\n \"transaction_id\": \"TRANSACTION123456789\",\n \"merchant_id\": \"Customer1234\",\n \"biz_id\": \"VA1234\"\n}\n\n๐ค Response
\n๐ FX object
\n๐ Order amount object
\n๐ Detail object
\n","urlObject":{"path":["v2","currentz","exchange","create"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"63cef29a-b6e9-488d-9d57-a0302694b48a"},{"name":"webhook FX transactions","id":"624207c1-13d1-4d5a-a681-66183a46f790","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"type":"default","value":"application/json; charset=utf-8","key":"Content-Type"},{"type":"default","value":"currents.exchange","key":"topic"}],"body":{"mode":"raw","raw":"{\n \"order_id\":\"๐ช FX transactions webhook
\nNotification of Foreign Exchange (FX) transaction
\nThe currents.exchange webhook is where you listen for the status and details of an FX transaction, i.e. all transactions where the order_type is exchange.
Monitoring currency exchange status
\nThe FX order status will change from PENDING to either SUCCESS or FAIL.
Webhook: currents.exchange
\n๐ Order_amount object
\n๐ Detail object
\n","urlObject":{"protocol":"https","path":["webhook","pp"],"host":["customer","domain","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"624207c1-13d1-4d5a-a681-66183a46f790"}],"id":"e338d386-9539-4467-aed4-2a3c581760b3","description":"The /exchange endpoint enables the conversion of currencies, either between the balances held by your customer or when making a payment in a non-balance currency.
Currency exchange is available 24 hours a day, 7 days a week, 365 days a year, including all public holidays.
\n๐ How to convert currencies
\n- \n
- Query an exchange rate to obtain the current one (usually valid for 60 seconds). \n
- Exchange currencies by creating an FX transaction. \n
- Check the status of the transaction. The
currents.exchangewebhook is where you listen for the status and details of a foreign exchange transaction, i.e. all transactions where theorder_typeisexchange. \n