Pay In transaction APIs v2

The v2 Pay In transaction APIs have two major improvements over Payabli’s core payment processing endpoints: unified response codes and automatic transaction details in responses.

What’s different in v2

These next sections cover the main differences between v1 and v2 transaction APIs.

All v2 endpoints return responses using a standardized code format that makes it easier to understand transaction outcomes and handle them consistently across your application.

Response code categories

v2 APIs use a three-tier code structure that groups outcomes by type:

• A codes (A0000-A0099): Approved transactions: payment was successfully processed
• D codes (D0100-D2999): Declined transactions: payment was rejected by the card network or issuer
• E codes (E3000-E9999): Error conditions: technical or validation errors prevented processing

This structure lets you handle responses at different levels of specificity. For example, you can check if a code starts with “A” for any approval, or check for specific codes like “D0225” (insufficient funds) to provide targeted messaging.

See the Pay In unified response codes reference for the complete list of all codes for errors, approvals, and declines.

Approved and Declined response format

Every v2 Approval and Decline response includes four key fields that offer context about the outcome:

• code: The standardized response code (for example, A0000, D0110, E5001)
• reason: Human-readable reason for the outcome (for example, “Approved”, “Insufficient Funds”)
• explanation: Detailed explanation of what happened and why
• action: Recommended next steps for handling this outcome

These fields are consistent across all v2 endpoints, making it easier to build reusable error handling and user messaging logic.

This is an example of a successful v2 transaction response:

1
  {
2
    "code": "A0000",
3
    "reason": "Approved",
4
    "explanation": "Approved by card network or card issuer.",
5
    "action": "No action required.",
6
    "data": {
7
      // transaction details object here
8
  },
9
    "token": null
10
  }

Decline responses follow the same structure, with appropriate code, reason, explanation, and action fields. All decline and approval responses automatically include complete transaction details in the response data object, eliminating the need for a separate API call to retrieve transaction information.

Error response format

Error responses (E codes) follow RFC 7807 Problem Details format, providing structured information about what went wrong:

• type: URI reference to documentation about this error type
• title: Short error title (for example, “Bad Request”)
• status: HTTP status code (for example, 400, 500)
• detail: Description of the specific error
• instance: The request URL that caused the error
• errors: Field-specific validation errors (for 400 Bad Request responses)

This standardized format makes it easier to debug issues and give helpful feedback to users.

When request validation fails, v2 endpoints return a 400 Bad Request response following RFC 7807 Problem Details format:

1
{
2
  "type": "https://docs.payabli.com/developers/references/pay-in-unified-response-codes",
3
  "title": "Bad Request",
4
  "status": 400,
5
  "detail": "Invalid CVV number",
6
  "instance": "/api/v2/MoneyIn/auth",
7
  "code": "E7016",
8
  "errors": {
9
    "paymentMethod.cvv": [
10
      {
11
        "message": "Invalid CVV number provided",
12
        "suggestion": "Provide a valid CVV number in payment method object"
13
      }
14
    ]
15
  },
16
  "token": null
17
}

The errors field provides detailed validation information for each field that failed validation, making it easier to identify and fix issues in your request.

Available v2 endpoints

The following endpoints are available in v2:

• POST /v2/MoneyIn/getpaid: Make a transaction (authorize and capture in one step)
• POST /v2/MoneyIn/authorize: Authorize a card transaction
• POST /v2/MoneyIn/capture/{transId}: Capture an authorized transaction (full or partial)
• POST /v2/MoneyIn/refund/{transId}/{amount}: Refund a settled transaction (full or partial)
• POST /v2/MoneyIn/void/{transId}: Void an unsettled transaction

Choosing v1 or v2

If you’re starting a new integration or want to take advantage of the enhanced features, use the v2 transaction APIs. They return standardized response codes, immediate transaction details, and clearer error messages.

Use v2 if:

• You’re starting a new integration
• You want standardized, predictable response codes
• You need transaction details immediately after processing
• You want clearer error messages and guidance

Use v1 if:

• You need backward compatibility with legacy systems

Migration guide

Migrating from v1 to v2 is straightforward. All v2 endpoints use the same authentication, request bodies, and path parameters as their v1 counterparts. Only the response format has changed.

1. Update endpoint paths: Add /v2 to the base path (for example /MoneyIn/getpaid becomes /v2/MoneyIn/getpaid)
2. Update response handling: Parse the new response structure with code, reason, explanation, action, and data fields
3. Update error handling: Map unified response codes to your application’s error handling
4. Test: The response structure is different, so ensure your integration handles all response scenarios correctly

See Pay In unified response codes reference for a full list of the new response codes.

Related resources

See these related resources to help you get the most out of Payabli.