dxp-ux

(0 reviews)

GET all Payments (TMF-676)

listPayment

This operation retrieves the payment history by using account number.

This operation is towards Aria, matrixx and csg(LCPR).

Request URL

https://[localhost]:[port]/dxp-ux/v1/{businessId}/payment

URL PARAMS

name	type	description	required
businessId	string	2 letter ISO 3166 country code (TT, BB, JM, PA, etc.) identifying the business unit.	Y

name	value	description	required
client_id	string	The client_id identifying the channel. Minimum characters: 5	Y
client_secret	string	Password associated with the client_id. Minimum characters: 5	Y
Correlation-ID	string	Identifier that correlates HTTP request between a client and server. Any identification model (UUDI, checksum, etc.) can be used, as long as it is a unique value to differentiate a transaction.	N It is Mandatory for business
channelId	string	Channel to business Allowed Value : APP	Y
lob	string	The Line of Business Identifier Allowed ENUM values: FIXED, PREPAID, POSTPAID	M For Matrixx not in scope
targetSystem	string	Expected target system: csg, matrixx, aria	This is for PR market(csg): M

Note :

To fetch payments from CSG System, need to pass targetSystem as "csg"
To fetch payments history from ARIA System, need to pass lob as "POSTPAID"
To fetch refund history from MATRIXX System, need to pass targetSystem as "matrixx"

Query Param

name	type	description	required
account_no	string	To retrieve the payments from a specific account	Y
startDate	string	To retrieve the payments performed after this date	N
endDate	string	To retrieve the payments performed before this date	N

Possible success responses:

1) Success response from Aria:

[ 200 ]

[
    {
        "id": "507953839",
        "description": "Tokenized Credit Card",
        "paymentDate": "2023-06-09T14:21:24Z",
        "@type": "Electronic Payment",
        "extendedCharacteristics": [
            {
                "name": "procStatusCode",
                "value": "1000"
            },
            {
                "name": "paymentDate",
                "value": "2023-06-09"
            },
            {
                "name": "procPaymentId",
                "value": "1673526085.24409"
            },
            {
                "name": "paymentMethodNo",
                "value": "3"
            }
        ],
        "amount": {
            "value": 22,
            "unit": "usd"
        },
        "paymentMethod": {
            "id": "SALESFORCE003_PM_019",
            "@type": "Tokenized Credit Card"
        },
        "status": "Approved",
        "statusDate": "2023-06-09T14:21:24Z"
    }
]

2) Success response from Matrixx:

[
    {
        "id": "21",
        "description": "PURC:110.39:91",
        "paymentDate": "2022-08-25T08:59:17.241928Z",
        "status": "settled",
        "account": {
            "id": "S-8919414203",
            "@type": "SubscriptionRef"
        },
        "paymentMethod": {
            "id": "",
            "@type": "PaymentMethodRef"
        },
        "refund": [
            {
                "id": "IDN0:1:52:7435",
                "totalAmount": {
                    "value": 3.0,
                    "unit": "USD"
                },
                "status": "refunded",
                "refundDate": "2022-09-23T12:25:56.260859Z",
                "@type": "RefundRef"
            }
        ],
        "totalAmount": {
            "value": 110.39,
            "unit": "USD"
        }
    },
    {
        "id": "22",
        "description": "PURC:110.39:91",
        "paymentDate": "2022-08-25T10:33:09.998424Z",
        "status": "settled",
        "account": {
            "id": "S-8919414203",
            "@type": "SubscriptionRef"
        },
        "paymentMethod": {
            "id": "",
            "@type": "PaymentMethodRef"
        },
        "refund": [],
        "totalAmount": {
            "value": 110.39,
            "unit": "USD"
        }
    }
]

[ 200 ]

PR FIXED CSG

OK - listPayment request processed successfully, response body contains an entity corresponding to the requested resource.

[
    {
        "id": "8759294000000010",
        "correlatorId": "EFTPY0704",
        "paymentDate": "2024-07-05T00:00:00:000Z",
        "statusDate": "2024-07-05T00:00:00:000Z",
        "name": "",
        "totalAmount": {
            "amount": "-44.04"
        },
        "account": {
            "id": "8211990010031540",
            "name": "JANE ,DOE1"
        },
        "paymentItem": [
            {
                "totalAmount": {
                    "amount": "-44.04"
                }
            }
        ],
        "item": {
            "referredType": ""
        },
        "paymentMethod": {
            "@type": "EFT PAYMENT",
            "details": {
                "type": "",
                "cardNumber": "",
                "expirationDate": ""
            }
        }
    },
    {
        "id": "8759394000000010",
        "correlatorId": "EFTPY0604",
        "paymentDate": "2024-06-05T00:00:00:000Z",
        "statusDate": "2024-06-05T00:00:00:000Z",
        "name": "",
        "totalAmount": {
            "amount": "-42.89"
        },
        "account": {
            "id": "8211990010031540",
            "name": "JANE ,DOE1"
        },
        "paymentItem": [
            {
                "totalAmount": {
                    "amount": "-42.89"
                }
            }
        ],
        "item": {
            "referredType": ""
        },
        "paymentMethod": {
            "@type": "EFT PAYMENT",
            "details": {
                "type": "",
                "cardNumber": "",
                "expirationDate": ""
            }
        }
    },
    {
        "id": "8759494000000010",
        "correlatorId": "EFTPY0504",
        "paymentDate": "2024-05-05T00:00:00:000Z",
        "statusDate": "2024-05-05T00:00:00:000Z",
        "name": "",
        "totalAmount": {
            "amount": "-42.89"
        },
        "account": {
            "id": "8211990010031540",
            "name": "JANE ,DOE1"
        },
        "paymentItem": [
            {
                "totalAmount": {
                    "amount": "-42.89"
                }
            }
        ],
        "item": {
            "referredType": ""
        },
        "paymentMethod": {
            "@type": "EFT PAYMENT",
            "details": {
                "type": "",
                "cardNumber": "",
                "expirationDate": ""
            }
        }
    }
]

JM LIBERATE RESPONSE

[
    {
        "id": "549114227",
        "correlatorId": "987654321",
        "paymentDate": "2023-01-02T08:41:57.000Z",
        "statusDate": "2023-01-02T08:41:57.000Z",
        "status": "",
        "name": "FAC",
        "totalAmount": {
            "amount": 500.00
        },
        "amount": {
            "amount": 500.00
        },
        "account": {
            "id": "325152270000",
            "name": "on, Test"
        },
        "paymentItem": [
            {
                "totalAmount": {
                    "amount": 500.00
                }
            },
            {
                "item": {
                    "id": "DEPOSIT",
                    "referredType": "deposit"
                }
            }
        ],
        "paymentMethod": {
            "@type": "E",
            "details": {
                "type": "D",
                "cardNumber": "",
                "expirationDate": ""
            }
        }
    },
    {
        "id": "549114226",
        "correlatorId": "987654321",
        "paymentDate": "2023-01-02T08:41:57.000Z",
        "statusDate": "2023-01-02T08:41:57.000Z",
        "status": "",
        "name": "FAC",
        "totalAmount": {
            "amount": 404.00
        },
        "amount": {
            "amount": 404.00
        },
        "account": {
            "id": "325152270000",
            "name": "on, Test"
        },
        "paymentItem": [
            {
                "totalAmount": {
                    "amount": 404.00
                }
            },
            {
                "item": {
                    "id": "UNALLOC",
                    "referredType": "payment"
                }
            }
        ],
        "paymentMethod": {
            "@type": "E",
            "details": {
                "type": "S",
                "cardNumber": "",
                "expirationDate": ""
            }
        }
    }
]

JM CERILLION RESPONSE

[
    {
        "id": "28372884",
        "correlatorId": "Aria 247830253756",
        "statusDate": "2022-02-03T17:28:33.000Z",
        "paymentDate": "2022-02-03T00:00:00.000Z",
        "taxAmount": {
            "amount": "0.0"
        },
        "amount": {
            "amount": "-7400.0"
        },
        "totalAmount": {
            "amount": "-7400.0"
        },
        "account": {
            "id": "50146303"
        },
        "item": {
            "id": "265078124",
            "referredType": "payment"
        },
        "paymentMethod": {
            "@type": "Cash"
        }
    },
    {
        "id": "27933708",
        "correlatorId": "F8786312",
        "statusDate": "2021-12-03T10:54:57.000Z",
        "paymentDate": "2021-12-02T00:00:00.000Z",
        "taxAmount": {
            "amount": "0.0"
        },
        "amount": {
            "amount": "-8265.16"
        },
        "totalAmount": {
            "amount": "-8265.16"
        },
        "account": {
            "id": "50146303"
        },
        "item": {
            "id": "257831491",
            "referredType": "payment"
        },
        "paymentMethod": {
            "@type": "Scotia Bank"
        }
    },
    {
        "id": "27482404",
        "correlatorId": "kiosk tut4vqzy3ea",
        "statusDate": "2021-09-24T10:37:10.000Z",
        "paymentDate": "2021-09-24T00:00:00.000Z",
        "taxAmount": {
            "amount": "0.0"
        },
        "amount": {
            "amount": "-26000.0"
        },
        "totalAmount": {
            "amount": "-26000.0"
        },
        "account": {
            "id": "50146303"
        },
        "item": {
            "id": "249646526",
            "referredType": "payment"
        },
        "paymentMethod": {
            "@type": "Cash"
        }
    }
]

Definitions

Response Data Model:

name	type	description	required
id	string	Unique identifier assigned for the transaction by target system	N
href	string	Hypertext Reference of the Payment	N
authorizationCode	string	Authorization code retrieved from an external payment gateway that could be used for conciliation	N
correlatorId	string	Unique identifier in the client for the payment in case it is needed to correlate	N
description	string	Specifies the source of the payment. Possible Values:Tokenized Credit Card, Electronic Check (ACH), External Payment	N
name	string	Screen name of the payment	N
paymentDate	datetime	Date and Time of payment	N
status	string	Specifies the status of the payment Example: Approved	N
statusDate	datetime	The date when payment was received	N
account	object	Account reference. A account may be a party account or a financial account.	N
account.id	string	Unique identifier of the account	N
account.href	string	Reference of the account	N
account.description	string	Detailed description of the account	N
account.name	string	Name of the account	N
account.@baseType	string	When sub-classing, this defines the super-class	N
account.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
account.@type	string	When sub-classing, this defines the sub-class entity name	N
account.@referredType	string	The actual type of the target instance when needed for disambiguation	N
amount	object	Amount to be paid (net of taxes)	N
amount.value	number, float	Amount paid	N
amount.unit	string	Currency (ISO4217 norm uses 3 letters to define the currency)	N
channel	object	The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..	N
channel.id	string	Unique identifier of the related entity.	N
channel.href	string	Reference of the related entity.	N
channel.name	string	Name of the related entity.	N
channel.@baseType	string	When sub-classing, this defines the super-class	N
channel.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
channel.@type	string	When sub-classing, this defines the sub-class entity name	N
channel.@referredType	string	The actual type of the target instance when needed for disambiguation	N
payer	object	Related Entity reference. A related party defines party or party role linked to a specific entity.	N
payer.id	string	Unique identifier of the related entity.	N
payer.href	string	Reference of the related entity.	N
payer.name	string	Name of the related entity.	N
payer.role	string	Role played by the related party	N
payer.@baseType	string	When sub-classing, this defines the super-class	N
payer.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
payer.@type	string	When sub-classing, this defines the sub-class entity name	N
payer.@referredType	string	The actual type of the target instance when needed for disambiguation	N
paymentItem	object array	The paymentItem is the result of lettering process. It enables to assign automatically or manually part of incoming payment amount to a bill	N
paymentItem.id	string	Unique identifier of the payment Item	N
paymentItem.amount	amount	Amount to be paid (net of taxes)	N
paymentItem.item	channel		N
paymentItem.taxAmount	amount	Tax applied	N
paymentItem.totalAmount	MoneyType	Amount to be paid (including taxes)	N
paymentItem.@baseType	string	When sub-classing, this defines the super-class	N
paymentItem.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
paymentItem.@type	string	When sub-classing, this defines the sub-class entity name	N
paymentMethod	object	link to the resource that holds information about the payment mean used to complete the operation	N
paymentMethod.id	string	The client-defined identifier of the payment method used for payment.	N
paymentMethod.href	string	A resource URI pointing to the resource in the server that stores the detailed information. This is typically the resource url to retrieve individual details for the specific payment method	N
paymentMethod.description	string	Text describing the contents of the payment method	N
paymentMethod.isPreferred	boolean	If the method is the preferred one by the owner. Typically used when querying for the payment methods of a specific customer or account	N
paymentMethod.name	string	Friendly name assigned to the payment method	N
paymentMethod.status	string	status of the payment(ex: approved)	N
paymentMethod.statusDate	datetime	Date of updated status for payment	N
paymentMethod.account	account[]	Account reference. A account may be a party account or a financial account.	N
paymentMethod.relatedParty	payer	Related Entity reference. A related party defines party or party role linked to a specific entity.	N
paymentMethod.validFor	object	Date interval in which the payment method is valid	N
paymentMethod.validFor.endDateTime	datetime	End of the time period, using IETC-RFC-3339 format	N
paymentMethod.validFor.startDateTime	datetime	Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end	N
paymentMethod.@baseType	string	When sub-classing, this defines the super-class	N
paymentMethod.@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
paymentMethod.@type	string	Number of payment description type, as already stored in DB (ex: 1=credit card, 5= net terms, etc) Note: if we see below numbers in response then pass 'static string' like below 13 = "Tokenized Credit Card" 2 = "Electronic Check" (ACH)-1 = "External Payment" ELSE pass the numbers whatever coming in response	N
paymentMethod.details	Object	Definition of the payment method. Its content depends on the type field	N
paymentMethod.@referredType	string	The actual type of the target instance when needed for disambiguation	N
paymentMethod. details	object	Details of payment method	N
paymentMethod. details .type	string	Type of payment method	N
paymentMethod. details .cardNumber	string	Card Number	N
paymentMethod. details .expirationDate	string	Card Expiry Date	N
taxAmount	amount	Tax applied	N
totalAmount	object	Amount to be paid (including taxes)	N
totalAmount.amount	string	Amount to be paid (including taxes)	N
@baseType	string	When sub-classing, this defines the super-class	N
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships	N
extendedCharacteristics	array	Represents additional attributes of payment entity	N
extendedCharacteristics.name	string	name of the additional attributes (ex: "paymentDate", "procStatusCode")	N
extendedCharacteristics.value	string	value of the additional attributes(ex: "2023-06-09", 100)	N
@type	string	Specifies the payment type Note: These are the possible payment type "Electronic Payment", "3rd party payment", "Write Off", "Balance Forward", "Cash Credit", "Credit From Overpayment", "Credit memo line"	N
item	EntityRefType	Reference where to get more information about the entity with another API call	N
refund	array	array for the refund details	N
refund.id	string	Refunded id (unique) from matrixx	N
refund.totalAmount	object	refund amount details	N
refund.totalAmount.value	integer	refund amount value	N
refund.totalAmount.unit	string	Currency (ISO4217 norm uses 3 letters to define the currency)	N
refund.status	string	staus of the refund(ex: refunded)	N
refund.refundDate	DateTime	Date of the refund	N
refund.@type	string	When sub-classing, this defines the sub-class entity name(ex: "RefundRef")	N
totalAmount.value	Number	Amount paid (including taxes)	N
totalAmount.unit	string	Currency (ISO4217 norm uses 3 letters to define the currency)	N

extendedCharacteristics

name	type	description	required
procStatusCode	string	Response code from payment processor (Braintree). Possible Values:1000(Approved), 4001(settlement_declined), 4000(settled), 81706(CVV is required)	N
paymentDate	string	Processor payment date	N
procPaymentId	string	The processor payment ID	N
paymentMethodNo	string	Processor payment method number	N

Possible response error

In this section all the possible data structures received by the client are defined and that must be considered as unsatisfactory when responding to the method.

[ 400 ]

Bad Request - the request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

{
  "errors" : [{
      "code" : 400,
      "message" : "The request is invalid or not properly formed.",
      "description" : "The client sent too many requests and server is not able to serve them all at the moment"
    }]
}
{
    "errors": [{
        "code": 404,
        "message": "Aria : Error While Fetching Payments - 12345678",
        "description": "Invalid Account Number for BusinessID : JM"
    }]
}

[ 401 ]

Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.

{
  "errors" : [{
      "code" : 401,
      "message" : "The user could not be authenticated for this request.",
      "description" : "The request has not been applied because it lacks valid authentication credentials for the target resource"
    }]
}

[ 403 ]

Forbidden - Indicates that the server understood the request but refuses to fulfill it. If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials.

[ 404 ]

Not Found - server has not found a resource with that URI. This may be temporary and permanent condition. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

{
  "errors" : [{
      "code" : 404,
      "message" : "The request is invalid or not properly formed.",
      "description" : "The requested operation failed because a resource associated with the request could not be found."
    }]
}

[ 405 ]

Method Not Allowed - HTTP method not allowed for this resource. The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

{
    "errors": [{
            "code": 405,
             "message": "APIKIT:METHOD_NOT_ALLOWED",
             "description": "HTTP Method post not allowed for : /{businessId}/payment"
        }]
}

[ 429 ]

Too Many Requests - client has sent too many requests in a space of time (rate limiting). When a server is under attack or just receiving a very large number of requests from a single party, responding to each with a 429 status code will consume resources. Therefore, servers may drop connections or take other steps instead of responding with the 429 status code, when limiting resource usage.

{
  "errors" : [{

      "code" : 429,
       "message" : "The request is invalid or not properly formed.",
      "description" : "The requested operation failed because a resource associated with the request could not be found."
    }]
}

Reviews

GET all Payments (TMF-676)

listPayment

Request URL

URL PARAMS

Header

Query Param

Possible success responses:

[ 200 ]

[ 200 ]

Definitions

extendedCharacteristics

Possible response error

[ 400 ]

[ 401 ]

[ 403 ]

[ 404 ]

[ 405 ]

[ 429 ]

Reviews