Authorization Guide
This Authorization Guide covers the differences between VRNs and Synthetic Accounts, various authorization use cases, detailed instructions on how to approve or deny transactions using the specified API endpoint, and specific denial reasons by transaction type. This guide serves as a valuable resource for developers and users to manage transaction authorizations effectively and efficiently.
Note
Auth capabilities are designed to be used in conjunction with VRNs.
VRNs vs. Synthetic Accounts?
It's important to remember that VRNs are not actual accounts, but rather pointers to accounts. When comparing them against Synthetic Accounts you will recognize the have following key differences:
- VRNs do not hold balance or maintain any balance reporting.
- VRNs cannot originate payments; they only accept (or receive) payments.
- VRNs are not a depository products, and therefore don't receive the same protections, as FDIC insurance.
VRN Specific Authorization Use Cases
| Use Case | Description |
|---|---|
| External Ledger Alignment: | Tie stored funds products to a corresponding VRN to maintain reporting, reconciliation, and create an auditable trail for financial activity. |
| Payment Acceptance and Controls: | Utilize payment authorization logic to review and approve received traffic to managed VRNs, establishing a control layer for payment acceptance. |
| Mitigating Fraud Risk: | Use VRNs for one-time payment acceptance without providing an account number to reduce fraud risk and archive VRNs if fraudulent activity is detected. |
For more information please visit our VRN Guide.
Other Authorization Use Cases
| Category | Use Case | Description |
|---|---|---|
| Automated Transaction Management | Scheduled Transaction Approvals | Clients can set up automated rules to approve or deny transactions based on predefined criteria, such as transaction amount, frequency, or recipient. This helps streamline transaction management and reduces manual intervention. |
| Customizable Authorization Rules | Dynamic Authorization Criteria | Allow clients to define custom authorization rules based on their specific business needs. For example, transactions above a certain threshold may require additional approval steps, or transactions to specific countries may be flagged for review. |
| Real-Time Fraud Detection | Instant Fraud Alerts | Integrate real-time fraud detection mechanisms that automatically deny transactions flagged as suspicious. Clients receive instant alerts and can review the transaction details to confirm or override the denial. |
| Compliance and Regulatory Checks | Regulatory Compliance Verification | Ensure transactions comply with relevant regulations by incorporating compliance checks into the authorization process. Transactions that fail to meet compliance standards can be automatically denied, with detailed reasons provided. |
| User Role-Based Authorization | Role-Based Access Control | Implement role-based access control to manage transaction authorizations. Different user roles within the client's organization can have varying levels of authorization power, ensuring that sensitive transactions are handled by authorized personnel only. |
| Batch Transaction Processing | Bulk Authorization | Enable clients to approve or deny multiple transactions in a single request. This is particularly useful for businesses that process a high volume of transactions and need efficient batch processing capabilities. |
| Detailed Audit Trails | Comprehensive Audit Logs | Maintain detailed audit logs for all transaction authorizations, including timestamps, user actions, and authorization statuses. This helps clients track and review authorization activities for compliance and internal audits. |
| Geo-Location Based Authorization | Location-Based Rules | Implement authorization rules based on the geographic location of the transaction, adding an extra layer of security for international transactions. |
| - Time-Based Authorization | Time-Specific Rules | Set up authorization rules that only allow transactions during specific times or business hours, reducing the risk of unauthorized access outside of these periods. |
Approve or Deny a Transaction
The "Approve or Deny a Transaction" endpoint allows you to manage the authorization status of a specific transaction. By sending a PUT request to this endpoint with the necessary parameters, you can either approve or deny a transaction, providing detailed reasons and memos if needed. This ensures that each transaction is processed according to your specified criteria and requirements.
Endpoint:
Path Parameters
- uid (string, required): Newline-generated unique ID specific to the current endpoint.
Body Parameters
- authorization_status (string, required): The current status of the transaction authorization.
- client_approved
- denied_memo (string, optional): The memo attached to the transaction if it has been denied.
- denied_reason (string, required if denied): The reason for the authorization denial.
Denial Reasons by Transaction Type
In this section, you'll find the specific reasons required for denying a transaction based on its type. Different criteria apply to wire transactions and ACH transactions, ensuring that each denial reason is appropriately categorized and justified according to the transaction's nature.
| For wire transactions, must be one of: | For ACH transactions, must be one of: |
|---|---|
| - vrn_archived | - vrn_archived |
| - vrn_locked | - vrn_locked |
| - international_payment | - debit_limit_exceeded |
| - unauthorized_credit | - unauthorized_credit |
| - unauthorized_debit | |
| - insufficient_funds |
Headers
- x-trace-id (string, required): A unique identifier provided for each request. Duplicate values submitted in requests within 7 days of each other will cause the request to be rejected.
Steps to Authorize or Deny a Transaction
1. Prepare the Request:
- Ensure you have the unique transaction ID (uid).
- Determine the authorization_status (e.g., client_approved or denied).
- If denying, prepare the denied_memo and denied_reason.
2. Set Headers:
- Include the x-trace-id in the request headers.
3. Send the Request:
- Make a PUT request to https://sandbox.newline53.com/api/v1/transactions/{uid}/authorize with the necessary path and body parameters.
4. Handle the Response:
- 200: The authorization resource is returned.
- 400: Handle errors such as bad authorization request, status error, decision window expired, or ineligible transaction.
- 422: Handle exceptions that occurred while authorizing the transaction.
Responses
When you send a request to authorize or deny a transaction, you will receive one of several possible responses. These responses indicate whether the request was successful or if there were any issues that need to be addressed. Below are the potential responses you might encounter:
- 200: The authorization resource is returned.
- 400: Bad authorization request.
- 400: Transaction authorization status error.
- 400: Transaction authorization decision window expired.
- 400: Transaction ineligible for authorization.
- 422: An exception occurred while authorizing the transaction.
Example Success Response
This example demonstrates a successful transaction authorization response, including details such as the finalized authorization status and any relevant memos or reasons for denial.
{
"authorization": {
"authorization_finalized_at": "2024-10-9T00:12:53.729Z",
"authorization_required_by": "2024-10-10T00:18:53.729Z",
"authorization_status": "client_denied",
"denied_memo": "denied memo",
"denied_reason": "debit_limit_exceeded"
}
}
Example Error Response
This example illustrates an error response when a transaction authorization request fails, providing specific error codes, titles, and detailed messages to help diagnose the issue.
{
"errors": [
{
"code": 6009,
"title": "Transaction cannot be authorized",
"detail": "Authorization status does not allow updates",
"occurred_at": "2023-10-04T13:23:04.345Z"
}
],
"status": 400
}
Updated 5 days ago