Guides

Recurring Payments via the Capture API

This guide details integration with our payment and payout API suite using the Capture API for processing transactions, including hosted, recurring, and direct payouts.

Suggest Edits

Introduction

This documentation provides a detailed integration guide for the payment and payout API suite, covering hosted payments, recurring billing, direct payouts, and in-store transactions. It specifies RESTful endpoints, JSON payload schemas, parameter validations, error handling, and security protocols, along with sample code and best practices for efficient integration.

🚧

Pre-requisites

API Credentials: Obtain merchantNo, storeNo, and verifySign values from Pockyt.

Webhook Configuration: Set up webhook URLs to receive asynchronous transaction updates.

Server Setup: A secure server for handling webhooks (ipnUrl) and callback URLs.

Compliance PCI compliance for handling credit card data if applicable.

API Diagram


API workflow

📘

API References for Endpoints in this Workflow:

Step-by-Step Description of the Recurring Payments Workflow

Step 1: Customer Checkout:

  • Action the customer needs to make a payment and intends to make additional payments in the future.

Step 2: Register Customer

  • Action: The Merchant Backend calls the Register Customer API to create a new customer in the Pockyt system. This step generates a unique customerNo, which will be used in subsequent steps. Pockyt captures information necessary for Address Verification Service (AVS), so it is crucial that the billing information provided matches the payment method's billing details.
  • Endpoint: POST /customers/create
  • Key Parameters:
    • Request Body: Includes customer information such as name, email, phone number, and address.
    • Response: Returns a customerNo, which is critical for linking this customer to payment actions.

Step 3: Make Payment and Enroll in Recurring

  • Action: This endpoint is used to directly send credit card information to Pockyt. NOTE: passing credit card data directly through this endpoint requires PCI SAQ D compliance. You will receive a webhook notification containing the vaultId parameter, which is essential for the next API call. The Merchant Backend calls the Capture API with the creditType set to vault and terminal set to "ONLINE" to enroll the payment method.
  • Endpoint: POST /order/v4/capture
    First Time Calling Capture API for Creating VaultId
curl -X POST "https://mapi.yuansferdev.com/order/v4/capture" \
     -H "Content-Type: application/json" \
     -d '{
  "merchantNo": "203780",
  "storeNo": "303661",
  "creditType": "vault",
    # "creditType" must be "vault" to store the payment method for future use.
  "amount": "20",
  "cardNumber": "4111111111111111",
  "cardExpYear": "2025",
  "cardExpMonth": "01",
  "cardCvv": "123",
  "currency": "USD",
  "customerNo": "2000357955353018248632",
    # "customerNo" is obtained from the previous step (customer registration).
  "reference": "FMlPbMIIjG",
  "settleCurrency": "USD",
  "vendor": "creditcard",
  "terminal": "ONLINE",
    # "terminal" must be set to "ONLINE" for vaulting to work correctly.
  "goodsInfo": "[{\"goods_name\":\"test\",\"quantity\":\"1\",\"category\":\"DIGITAL_GOODS\",\"description\":\"testing\",\"amount\":\"10.00\",\"tax\":\"0\"}, {\"goods_name\":\"test 2\",\"quantity\":\"1\",\"category\":\"DIGITAL_GOODS\",\"description\":\"testing\",\"amount\":\"10.00\",\"tax\":\"0\"}]",
  "ipnUrl": "https://apis.gwocu.com/api/webhook/listen/RecurringTransactionsWithCapture?apiKey=r1gt1lrf6dqpb105rtb0l9occaagfw0y",
    #"ipnUrl"  this is mandatory for receiving the webhook notification in the next step
  "callbackUrl": "https://demo.pockyt.io/",
  "verifySign": "0aa12ad27f9d0257019545c2879cf2fb"
}'
  • Key Parameters:
    • Request Body: Includes the customerNo from Step 2, the terminal value (ONLINE), and creditType value set to (vault).
    • Response: Returns authenticationUrl where you have to redirect user for authentication. Webhook received after this step contains a vaultId, which acts as the payment token for the associated payment method. However, the payment method is not charged at this stage.

Step 4: Authentication

In this step, you must use the authenticationUrl parameter received from the previous API call and redirect the customer to this URL. If you are redirected to the callbackUrl specified in the previous API call, it confirms that the customer has been successfully authenticated. However, if authentication fails, you will not receive a webhook notification under any circumstances.

Step 5: Handle Webhook Notification

  • Action: The webhook is triggered once the customer accepts the billing agreement in the checkout UI. However, the payment method has not been charged yet.
  • Purpose: The webhook includes the vaultId, which should be saved for future payments
  • See Example Webhook Notification Body Here

👍

Payment is completed only if the webhook notification's status parameter is success.

Step 6: Make Future Payment

  • Action: Using the vaultId obtained from the previous webhook notification, now there is not need to send credit card informatiion to the capture endpoint.
  • Endpoint: `POST /order/v4/capture
  • Key Parameters:
    • Request Body: Includes the transactionNo and vaultIdfrom Step 4.
    • Response: Returns the transaction status and transactionNo
curl -X POST "https://mapi.yuansferdev.com/order/v4/capture" \
     -H "Content-Type: application/json" \
     -d '{
  "merchantNo": "203780",
  "storeNo": "303661",
  "amount": "20",
  "vaultId": "pp_9cb9eb1892da49d2867c3d41bd73fedc",
  		#"vaultId" Received from the previous  webhook notification
  "currency": "USD",
  "creditType": "vault",
     # "creditType" must be "vault"
  "customerNo": "2000357955353018248632",
  "reference": "N0tNskuQRS",
  "settleCurrency": "USD",
  "vendor": "creditcard",
  "terminal": "ONLINE",
  "ipnUrl": "https://apis.gwocu.com/api/webhook/listen/RecurringTransactionsWithCapture2?apiKey=tvgu58v8f6p5d2gw2bfafsqdptr7kxa5",
  "callbackUrl": "https://demo.pockyt.io/",
  "goodsInfo": "[{\"goods_name\":\"test\",\"quantity\":\"1\",\"category\":\"DIGITAL_GOODS\",\"description\":\"testing\",\"amount\":\"10.00\",\"tax\":\"0\"}, {\"goods_name\":\"test 2\",\"quantity\":\"1\",\"category\":\"DIGITAL_GOODS\",\"description\":\"testing\",\"amount\":\"10.00\",\"tax\":\"0\"}]",
  "verifySign": "{{MySignature}}"
}'

Step 7: Handle Webhook Notification for Recurring Payments

  • Action: The Webhook Listener receives a second webhook notification from Pockyt, confirming the status of the recurring payment.
  • Purpose: This step ensures the Merchant Backend is notified of the success or failure of the recurring payment.
  • See Example Webhook Notification Body Here

👍

Payment is completed only if the webhook notification's status parameter is success

Key Notes for Implementation

  1. Parameters Flow:

    • customerNo: Generated in Step 2, used in Step 3 and 5.
    • transactionNo: Generated in Step 2, used in Step 3 and 5.
    • vaultId: Generated in Step 4, used in Step 5.

  2. Webhook Notifications:

    • Webhook notifications are crucial for confirming the status of transactions in Steps 3 and 6. Ensure the Webhook Listener processes the transactionNo and status fields properly.

Next Steps

Updated 11 days ago