Guides

Pockyt Integrated Payments Integration Guide

Suggest Edits

📘

Additional Resources:

Streamlined Integration of Recurring Payments and Vaulting with PayPal Using Pockyt Payments API.
This comprehensive tutorial will guide you through integrating recurring payments and vaulting features seamlessly into your application using PayPal and the Pockyt Payments API. By following these steps, you'll master the process of customer registration, secure payment transactions, and the implementation of vaulting for recurring payments.

Accepting Credit Card and PayPal Venmo Payments with Pockyt Integrated Payments

Step 1: Initiate Payment with SecurePay API

When a customer chooses to pay with a credit card at checkout, initiate a payment request to Pockyt’s SecurePay API endpoint. It's important to set the vendor value to creditcard and the terminal to YIP.

Example API Request:

{
    "amount": "100",
    "currency": "USD",
    "merchantNo": "203797",
    "reference": "ua4fdce33a3",
    "settleCurrency": "USD",
    "storeNo": "303714",
    "terminal": "YIP",
    "vendor": "paypal",
    "verifySign": "829bde3f722628b52597df2245ab7c47",
    "goodsInfo": "[{\"goods_name\":\"test\",\"quantity\":\"1\",\"category\":\"DIGITAL_GOODS\",\"description\":\"testing\",\"amount\":\"300\",\"tax\":\"0\"}]"
}

Example API Response:

{
    "result": {
        "transactionNo": "341992068123150527",
        "amount": "100.00",
        "currency": "USD",
        // Other response data...
        "clientToken": "<client_token>",
        "clientScript": "<client_script_url>"
    },
    "ret_code": "000100",
    "ret_msg": "success"
}

This response includes a client token and client script URL. You need to use these to display the payment form for the customer to enter their payment card details.

Step 2: Process the Order with Order API

After the customer enters their payment details and confirms the payment, you need to make a second API call to /order/v4/process. This request should include the transactionNo received from the first SecurePay API call.

Example API Request:

{
    "transactionNo": "341992068123150527",
    "merchantNo": "203797",
    "storeNo": "303714",
    "verifySign": "b5f37112384f4dc8b886e63a2a97cfa8",
    "timestamp": "2023-06-26T21:23:19Z"
}

Example API Response:

{
    "result": {
        "amount": "100.00",
        "currency": "USD",
        "status": "success",
        // Other response data...
    },
    "ret_msg": "success",
    "ret_code": "000100"
}

This response indicates the completion of the payment process. The status field will confirm the success of the transaction.

Step 3: Handling Asynchronous Notifications

After processing the payment, it's crucial to manage the asynchronous notifications regarding the transaction status. These notifications are a key part of the payment workflow in Pockyt's Integrated Payments system.

📘

Read more about handling Notifications Here

Process Overview:

  1. Set Up an IPN Listener: Configure an Instant Payment Notification (IPN) listener on your server. This listener will receive notifications from Pockyt about the status of each transaction.

  2. Receive Notifications: When a transaction status changes (e.g., from pending to successful), Pockyt sends a notification to your IPN listener URL. This notification includes essential transaction details and its current status.

  3. Validate and Process: Upon receiving a notification, validate its authenticity by checking the verifySign parameter. Then, update the transaction status in your system based on the received information.

  4. Respond to Pockyt: After processing the notification, respond to Pockyt with a success message. This acknowledgment is crucial to prevent repeated notifications.

Handling Notifications – Key Considerations:

  • Security: Ensure the security of the IPN listener and validate each notification to prevent fraudulent data processing.
  • Reliability: Design your system to handle possible network delays or multiple notifications for the same transaction status.

By effectively managing these asynchronous notifications, you ensure that your system stays updated with the latest transaction statuses, enhancing the reliability and integrity of your payment processing workflow.

Recurring Payments and Stored Payment Information with Pockyt Integrated Payments

Step 1: Customer Registration

Register Customer API Reference
To begin, let's register a customer and obtain a unique customerNo. Here's how you can do it:
Make a POST request to the /v1/customers/create endpoint with the provided request body using cURL.

Request:

{  
    "zip": "12345",  
    "firstName": "John",  
    "lastName": "Doe",  
    "customerCode": "CUST123",  
    "email": "[[email protected]](mailto:[email protected])",  
    "country": "US",  
    "city": "New York",  
    "dateOfBirth": "1990-01-01",  
    "phone": "555-123-4567",  
    "countryCode": "1",  
    "street": "123 Main St",  
    "street2": "Apt 4B",  
    "state": "NY",  
    "lang": "en",  
    "profileType": "individual",  
    "merchantNo": "MERCHANT123",  
    "storeNo": "STORE123",  
    "verifysign": "signature",  
    "company": "Example Company",  
    "mobileNumber": "555-987-6543"  
}

You'll receive a response containing the registered customer's details along with their customerNo.

{  
    "result":  
    {  
       "firstName":"Test",  
       "lastName":"Test",  
       "customerCode":"test08242021",  
       "createdTime":"2021-08-24T17:50:18Z",  
       "customerNo":"2000300192493466077324",  
       "email":"[[email protected]](mailto:[email protected])"  
    },  
    "ret_msg": "success",  
    "ret_code": "000100"  
}

Step 2: Secure-Pay with Vendor PayPal

Secure-Pay API Reference
Now, let's move on to initiating a secure payment request using PayPal as the vendor:

Create a request with essential parameters, including the customerNo, vendor as "paypal," creditType as "vault" and terminal as "YIP", along with the payment details.

{  
    "amount": "5.6",  
    "creditType": "vault",  
    "currency": "USD",  
    "customerNo": "2000305749483958992834",  
    "merchantNo": "202570",  
    "reference": "cw4bbc29f50334a2d7",  
    "settleCurrency": "USD",  
    "storeNo": "301945",  
    "terminal": "YIP",  
    "timeout": "120",  
    "vendor": "paypal",  
    "verifySign": "79dca0585a2e5e48535e744912c7aae6"  
}

The response will provide transaction details, including the transactionNo and a PayPal client script URL for the checkout process.

{  
    "result":  
    {  
        "reference": "cw4bbc29f50334a2d7",  
        "createdAt": "2023-07-05T10:40:08Z",  
        "amount": "5.60",  
        "orderId": "9YJ8144710699722K",  
        "clientToken": > "eyJicmFpbnRyZWUiOnsiYXV0aG9yaXphdGlvbkZpbmdlcnByaW50IjoiY2I2ZTVhNWE3NGI0N2I2NzZhNDIyY2UzMWY3NGNmYmMwMzQ5ZTM2MTMyNDY0NTUzODJjZDI5YWIxN2UyMWNkMXxtZXJjaGFudF9pZD1yd3dua3FnMnhnNTZobTJuJnB1YmxpY19rZXk9NjNrdm4zN3Z0MjlxYjRkZiZjcmVhdGVkX2F0PTIwMjMtMDctMDVUMTA6NDA6MTEuMzk1WiIsInZlcnNpb24iOiIzLXBheXBhbCJ9LCJwYXlwYWwiOnsiaWRUb2tlbiI6bnVsbCwiYWNjZXNzVG9rZW4iOiJBMjFBQUk5VjRuSXV2NWRZT1U3V2xLREtvVmUwdVk3RzdYODA0eDNfS08ySmFuZF83cXk3SDZGckFGWFBnX04yMFpNWEk3VjRvVE0yTlRVaEtMV21kc2c1OVNvd0VMOEl3In19",  
        "transactionNo": "303146182585830961",  
        "currency": "USD",  
        "clientScript": "<https://www.paypal.com/sdk/js?client-id=ARjuyiItvW8OAc2bw8Iv1Q20HgDPLwu1dQ-nmzBRD7zpkF5lUoz2jFC0Hz2ZjfGbfDNCLGN744kDf1n3&merchant-id=AAMZ8HV6NNS6J&intent=capture&components=buttons">  
    },  
    "ret_code": "000100",  
    "ret_msg": "success"  
}

Step 3: Display PayPal Checkout Script

Once you've obtained the transactionNo from the Secure-Pay response, you should display the PayPal client script URL on your merchant's checkout page.

Step 4: Payment Processing and Vault ID Retrieval

Process API Reference

When the user confirms the payment on PayPal, it's time to process the payment and obtain a vaultId for future recurring payments:
Call the /order/v4/process API by providing the transactionNo and other necessary details.

{  
    "transactionNo": "303146182585830961",  
    "merchantNo": "202570",  
    "storeNo": "301945",  
    "verifySign": "79d38c56a319228faeca9d42f7fd674a",  
    "timestamp": "2023-07-05T10:41:04Z"  
}  
The response will include a vaultId that you can utilize for upcoming recurring payment.

{  
    "result":  
    {  
        "reference": "cw4bbc29f50334a2d7",  
        "amount": "5.60",  
        "supUserid": "[[email protected]](mailto:[email protected])",  
        "vaultId": "ca_af748cc62c334c75b83844e53b76e9b1",  
        "transactionNo": "303146182585830961",  
        "vendorId": "4WS71249P6788492V",  
        "currency": "USD",  
        "paymentTime": "2023-07-05T10:41:08Z",  
        "customerNo": "2000305749483958992834",  
        "status": "success"  
    },  
    "ret_msg": "success",  
    "ret_code": "000100"  
}

Step 5: Implementing Future Recurring Payments

With the vaultId in hand, let's proceed to implement future recurring payments:

Make use of the /online/v4/secure-pay API once more, ensuring you set the creditType to "vault." Provide the customerNo and vaultId obtained earlier.

{  
    "amount": "299.98",  
    "creditType": "vault",  
    "currency": "USD",  
    "customerNo": "2000305749483958992834",  
    "merchantNo": "202570",  
    "reference": "1krxdd25urb6a32t1",  
    "settleCurrency": "USD",  
    "storeNo": "301945",  
    "terminal": "YIP",  
    "vaultId": "ca_af748cc62c334c75b83844e53b76e9b1",  
    "vendor": "paypal",  
    "verifySign": "38bb3afff2306647c100cc7bb5f2976a"  
}

The response will confirm the success of the recurring payment and provide relevant transaction details.

{  
    "result":  
    {  
        "amount": "299.98",  
        "customerNo": "2000305749483958992834",  
        "paymentTime": "2023-07-05T10:59:29Z",  
        "reference": "1krxdd25urb6a32t1",  
        "status": "success",  
        "transactionNo": "303147339985810581",  
        "vaultId": "ca_af748cc62c334c75b83844e53b76e9b1"  
    },  
    "ret_code": "000100",  
    "ret_msg": "success"  
}

Successfully Completing Recurring Payments

You've successfully implemented recurring payments and vaulting with PayPal using the Pockyt Payments API. Here's a quick recap of the steps:

  1. Register a customer and obtain their customerNo.
  2. Initiate a secure payment request with PayPal as the vendor.
  3. Display the PayPal client script URL on your checkout page.
  4. Process the payment, acquire the vaultId for future use.
  5. Implement recurring payments with the vaultId and customerNo.
  6. Receive confirmation and relevant details about the recurring payment.

Keep in mind that while this tutorial simplifies the process, you may need to adapt the steps and examples to match your specific programming environment and application structure.

SecurePay API

Description: SecurePay API serves as the cornerstone endpoint within Pockyt's Online Payment Processing product, catering to all scenarios, encompassing Pockyt Checkout and Server-to-Server Integrated Payments (YIP). Request and response structures can vary according to distinct use cases and implementations, necessitating reference to dedicated tutorials tailored to your desired checkout and payment flows.

Process API

Description: SecurePay API caters to all online payment scenarios, encompassing Pockyt Checkout and Server-to-Server Integrated Payments (YIP). Request and response structures can vary according to distinct use cases and implementations, necessitating reference to dedicated tutorials tailored to your desired checkout and payment flows.

PrePay API

Description: The PrePay API is a core element for merchants aiming to enable in-app payments through WeChatPay and AliPay. It supplies values like paymentNonce, paySign, and package parameters, which are necessary tools for seamless implementation within their mobile and native applications.

Register a Customer

Description: The Register Customer API enables the generation of new customer profiles and provides a unique Customer Number, which is essential for future interactions with the SecurePay API, particularly in recurring payment workflows.

Retrieve Customer Info

Description: The Register Customer API enables the generation of new customer profiles and provides a unique Customer Number, which is essential for future interactions with the SecurePay API, particularly in recurring payment workflows.

Update Customer Info

Description: Update Customer Info API is exclusively designed for modifying customer contact information. It serves as a dedicated endpoint for updating customer details such as their contact information. It's important to note that this API is not intended for altering payment credentials, as this functionality should be handled separately through the Update Token API.

PrePay WeChat Mini Payments API

Description: The PrePay API enables mobile payments specifically tailored for WeChat Mini Programs and In-App solutions. This API handles payment processing seamlessly within the WeChat Mini Program environment, offering a convenient and efficient payment experience for users.

Updated 12 months ago