Card Binding to Obtain Credentials

About 203 wordsLess than 1 minute

View as Markdown

2025-03-07

POST

📍How to choose a site? See API Endpoint Guide

Request Body Parameters

application/json

Common Request Parameters

bizContent

paymentMethodObjectRequired
The type and detailed information of the payment method to be used.
- typeString(32)Required
  Payment methods:
  scheme International credit card payment
  Local payment methods Optional values: Non-Hosted Supported APMs
- scanCodeIdStringConditional
  Payment code generated by the customer's mobile wallet client. Usually displayed in the form of a barcode or QR code. The merchant terminal scans the customer's phone screen to obtain the code
- cardInfoObjectConditional
  Cardholder information, mandatory for credit card payments when not using a linked card
  - numberString(64)Required
    International credit card number
  - pinString(2)Optional
    First two digits of the local card password
  - holderFirstNameStringRequired
    Cardholder's first name, character type, no special symbols
  - holderLastNameStringRequired
    Cardholder's last name, character type, no special symbols
  - expireMonthString(2)Required
    Expiration month, 2 digits
  - expireYearString(4)Required
    Expiration year, 4 digits
  - cvvString(4)Required
    Credit card CVV, Visa/MasterCard/JCB/Discover/Diners Club CVV is three characters long, American Express CVV may be four characters long
threeDSRequestDataStringConditional
3DS verification request parameters. See the see the 3DS Integration Guide for details
- executeThreeDStringConditional
  3DS verification execution policy: \
  Y - Force 3DS verification and use PingPongCheckout's 3DS
  depends - Whether to conduct 3DS verification is decided by PingPongCheckout's risk control decision
  external - 3DS verification is required, but 3DS parameters are collected by the merchant and executed by PingPong. Note: This option is not applicable for the checkout
- authenticationValueStringConditional
  A unique identifier generated by the issuing bank for Visa, American Express, JCB, Diners Club, and Discover transactions after customer authentication. The raw data is in base64 units. It needs to be converted into the correct format.
- acsTransactionIdStringConditional
  A unique transaction identifier assigned by the ACS to identify individual transactions.
- veresEnrolledStringConditional
  Result of the registration check. This field can contain one of the following values: \
  Y - Card is registered or can be registered; you must authenticate. Liability shift.
  N - Unregistered card; proceed with authorization. No liability shift.
  U - Authentication could not be performed for any reason. No liability shift
- specificationVersionStringConditional
  This field contains the 3D Secure version used to process the transaction. For example, 1.0.2 or 2.0.0.
- directoryServerTransactionIdStringConditional
  Directory Server Transaction ID generated by the Mastercard Directory Server during the authentication transaction and passed back to the merchant along with the authentication result.
- threeDSServerTransactionIdStringConditional
  A unique transaction identifier assigned by the 3DS server to identify individual transactions.
- paresStatusStringConditional
  Original result of the authentication check. This field can contain one of the following values: \
  A - Evidence of an authentication attempt has been generated.
  N - Customer authentication failed or was canceled. Transaction denied.
  U - Authentication was not completed for any reason.
  Y - Customer has successfully authenticated.
- eciStringConditional
  For validation, only for Visa, American Express, JCB, Diners Club, and Discover transactions, return the numeric e-commerce indicator (ECI). Missing field upon authentication failure. This field contains one of the following values: \
  01 - Attempted authentication (Mastercard)
  02 - Successful authentication (Mastercard)
  05 - Successful authentication (Visa, American Express, JCB, UNION PAY, Diners Club, and Discover)
  06 - Attempted authentication (Visa, American Express, JCB, Diners Club, and Discover)
requestIdString(64)Required
Unique request number, globally unique
merchantUserIdString(256)Conditional
Member ID, the user's member ID on the merchant's website, applicable for quick payment scenarios, not required for guest identity
jsGeneratedDataString(256)Conditional
Card payments must integrate the risk control component, this parameter is required for card payments. If acquisition fails, an empty string can be passed, which will not block the payment process. By embedding the risk control component provided by PingPong, obtain the JSON string of browser-related information and pass it to this parameter. For merchants using the risk control plugin, see the see the 3DS Integration Guide
notificationUrlString(255)Optional
A custom address set by the merchant for notifying the transaction result. Once this parameter is filled, PingPongCheckout will asynchronously push the transaction result to this address via POST.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications.
languageString(12)Optional
Used to specify the language of the PingPong checkout, defaults to en if not provided. See Appendix List of Supported Checkout Languages for details

Other Parameters

Request Body Example

{
  "accId": "2022102018024210348883",
  "bizContent": {
    "merchantUserId": "12604896432523150",
    "requestId": "PMT-60KLMY78TS1716979870734",
    "payResultUrl": "https://test-acquirerpay.pingpongx.com/qa/result.html",
    "notificationUrl": "https://test-acquirerpay.pingpongx.com/qa/result.html",
    "bizType": "CardOnFile",
    "paymentMethod": {
      "type": "scheme",
      "cardInfo": {
        "cvv": "840",
        "number": "5299910010000015",
        "expireMonth": "12",
        "expireYear": "2025"
      }
    },
    "threeDSRequestData": {
      "executeThreeD": "Y"
    },
    "browserInfo": {
      "acceptHeader": "content-type=application/x-www-form-urlencoded;accept=*/*;cache-control=no-cache;postman-token=cf489264-5378-4d5d-a86c-72c86a408c03;accept-encoding=gzip, deflate;content-length=588;connection=keep-alive;",
      "colorDepth": "32",
      "jetLag": "480",
      "screenHeight": "1980",
      "screenWidth": "1080",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 Chrome/72.0.3626.121 Safari/537.36",
      "windowSize": "05",
      "javaEnabled": "true",
      "javaScriptEnabled": "true"
    },
    "jsGeneratedData": {
      "fingerprintId": "2018092714313010016549_PP20210608151727OB",
      "forterSiteId": "e088dda90c4e",
      "forterTokenCookie": "c3402ed6f84d4c50add3458a1ce51d60_1623137756842_87_UDF43_11ck",
      "orderTerminal": "03",
      "threeDSServerTransID": ""
    },
    "customer": {
      "email": "3ds@pingpongx.com",
      "firstName": "James",
      "lastName": "LeBron",
      "identificationId": "",
      "identificationType": "ID",
      "phone": "3055787343",
      "birthDate": ""
    },
    "device": {
      "orderTerminal": "02"
    }
  },
  "clientId": "2022102018024210348",
  "sign": "C218E7E812B93FEA20FD8F16C646B3BFD36D5898FC682427CC5815C139EC1ED9",
  "signType": "SHA256",
  "version": "1.0"
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

threeDUnionParamsStringOptional
3DS Address
- threeDRedirectUrlStringOptional
  3DS Redirect Address
transactionTimeStringOptional
Signing Time
transactionIdStringOptional
PP Signing Transaction Number
threeDContinueString(32)Conditional
Whether 3DS is required (for merchants using risk control plugin for verification processing):
- true: Yes
- false: No
merchantTransactionIdStringOptional
Merchant Signing Order Number
statusStringOptional
Signing Status, if 3DS is required, the signing status is INIT

Request Body Example

{
  "accId": "2022102018024210348883",
  "bizContent": {
    "transactionTime": "1716979873000",
    "threeDUnionParams": {
      "threeDRedirectUrl": "https://test-acquirer-static.pingpongx.com/payment/threeDs.html?code=eyJhY3NVcmwiOiJodHRwczovL3gzZC1hbnktaW50LmNyZWRvcmF4Lm5ldC9jaGFsbGVuZ2UvcmVxdWVzdC9QSU5HUDk3OC8wZGNhYjk1NzAzYmIyMDQwOWYwOTcxZTA4ZTk1MjIzZDEyMDkiLCJ0aHJlZURTUmVzdWx0VXJsIjoibnVsbD90cmFuc2FjdGlvbklkPTIwMjQwNTI5NTAxMzkxNTUmbWVyY2hhbnRUcmFuc2FjdGlvbklkPVBNVC02MEtMTVk3OFRTMTcxNjk3OTg3MDczNCIsInJlcXVlc3RNZXRob2QiOiJHRVQiLCJjaGFubmVsIjoiQ0hBTk5FTCJ9"
    },
    "transactionId": "2024052950139155",
    "threeDContinue": "true",
    "merchantTransactionId": "PMT-60KLMY78TS1716979870734",
    "status": "INIT"
  },
  "clientId": "2022102018024210348",
  "code": "002000",
  "description": "Transaction processing",
  "sign": "2C1F98F56DB04ECEC7800E97B20D4A05153800CCD3BA52E7D3E60B49B0EB79BA",
  "signType": "SHA256"
}