Transaction Return API
Author:
Fluent Commerce
Changed on:
3 July 2024
Overview
An Order transaction defines the payment or refund details associated with an Order.
Key points
- Return Transaction Properties
- What you can do with Transaction
- Response on Failures
Return Transaction Properties
Below are the properties available in the Return Transaction object which can be updated and retrieved through the APIs in this document.
1. orderId
Type: String
Description:
1{ "orderId" : "1965797" }Language: json
Name: orderId
Description:
[Warning: empty required content area]The unique identifier assigned by Fluent Commerce.
2. transactionId
Type: String
Description:
1{ "transactionId" : "56473" }Language: json
Name: transactionId
Description:
[Warning: empty required content area]The unique transaction identifier assigned by Fluent Commerce.
3. transactionRef
Type: String
Description:
1{ "transactionRef" : "1442900790" }Language: java
Name: transactionRef
Description:
[Warning: empty required content area]The unique transaction reference provided by the Retailer to the payment gateway.
For refunds, it contains the transaction Id provided by the gateway to Fluent Commerce when a refund is processed.
4. transactionType
Type: String
Description:
1{ "transactionType" : "PAYMENT" }Language: java
Name: transactionType
Description:
[Warning: empty required content area]The type of transaction. Possible values are:
- PAYMENT - Order payment has been successfully processed via payment gateway.
- REFUND - Refund has been successfully processed via payment gateway integration.
- MANUAL REFUND - Transaction has been processed externally to the Fluent Retail system with the reference details saved in Admin Console.
5. amount
Type: Double
Description:
1{ "amount" : "59.90" }Language: json
Name: amount
Description:
[Warning: empty required content area]For transactionType = PAYMENT - The total transaction amount.
For transactionType = REFUND - The requested refund amount for a return.
6. currency
Type: String
Description:
1{ "currency" : "AUD" }Language: json
Name: currency
Description:
[Warning: empty required content area]The transaction currency. Possible values include 'AUD', 'NZD'.
7. transactionCode
Type: String
Description:
1{ "transactionCode" : "080920151234" }Language: java
Name: transactionCode
Description:
[Warning: empty required content area]The unique transaction ID or request ID provided by the payment gateway.
8. paymentProvider
Type: String
Description:
1{ "paymentProvider" : "PAYPAL" }Language: java
Name: paymentProvider
Description:
[Warning: empty required content area]The name of the payment gateway.
Possible values are:
- CYBERSOURCE
- GIVEX
- PAYPAL
- BRAINTREE
- AFTERPAY
9. paymentMethod
Type: String
Description:
1{ "paymentMethod" : "GIFTVOUCHER" }Language: json
Name: paymentMethod
Description:
[Warning: empty required content area]The way in which payment was made.
Possible values are:
- CREDITCARD
- PAYPAL'
- GIFTVOUCHER
- CASH
- AFTERPAY
10. cardType
Type: String
Description:
1{ "cardType" : "VISA" }Language: json
Name: cardType
Description:
[Warning: empty required content area]The card type used for the payment (if applicable)
Possible values are:
- MASTERCARD
- VISA
- AMEX
- DINERS
- DISCOVER
- UNIONPAY
- JCB
- MAESTRO
- INTERAC
11. status
Type: String
Description:
1{ "status" : "APPROVED" }Language: java
Name: status
Description:
[Warning: empty required content area]The transaction status.
Default value is APPROVED for all transactions not initiated by Fluent Retail System i.e. A payment transaction passed in by the retailer along with the order details will be in APPROVED state.
For a Refund initiated by Fluent Retail it can be:
- APPROVED - The Refund has been approved by the payment provider. A manual refund recorded in the system will be in approved state.
- PROCESSING - The refund is in progress with the payment provider.
- DECLINED - The refund has failed to process successfully.
12. createdOn
Type: DateTime
Description:
1{ "createdOn" : "2016-05-06T23:41:12.242Z" }Language: java
Name: createdOn
Description:
[Warning: empty required content area]Date/time when the transaction was created.
13. updateOn
Type: DateTime
Description:
1{ "updatedOn" : "2016-06-23T07:58:58.000+0000" }Language: java
Name: updateOn
Description:
[Warning: empty required content area]Date/time when the transaction was last updated.
What you can do with Transaction
Create a Return Transaction
Create a return Transaction in the Fluent Retail system
POST:
`/api/v4.1/return/{returnId}/transaction`Request Object
1returnTransactionRequest {
2
3 amount (double, compulsory),
4 cardType (string, optional) = 'MASTERCARD', 'VISA', 'AMEX', 'DINERS',
5 currency (string, compulsory) = 'AUD', 'NZD',
6 paymentMethod (string, compulsory) = 'CREDITCARD', 'PAYPAL', 'GIFTVOUCHER', 'CASH', 'AFTERPAY',
7 paymentProvider (string, compulsory) = 'CYBERSOURCE', 'GIVEX', 'PAYPAL', 'BRAINTREE', 'AFTERPAY',
8 transactionCode (string, compulsory),
9 transactionNote (string, optional),
10 transactionRef (string, compulsory),
11 transactionType (string, compulsory) = 'PAYMENT', 'REFUND', 'MANUAL REFUND'
12}Language: java
Name: Return Transaction Request Object
Description:
[Warning: empty required content area]Example request
1{
2 "transactionRef" : "123",
3 "transactionType" : "REFUND",
4 "amount" : 100,
5 "currency" : "AUD",
6 "paymentProvider": "PAYPAL",
7 "paymentMethod" : "PAYPAL",
8 "cardType" : null,
9 "transactionCode" : 2344
10 "transactionNote" : "Huge Transaction"
11}Language: java
Name: Example Request
Description:
[Warning: empty required content area]Response Object
1SuccessMessageResponse {
2
3 id (object, optional)
4}Language: java
Name: Response object
Description:
[Warning: empty required content area]Example response
1{
2 "id":"185330"
3}Language: java
Name: Example response
Description:
[Warning: empty required content area]View Return Transaction Details
Retrieve details for a single Transaction associated with a Return
GET:
`/api/v4.1/return/{returnId}/transaction/{transactionId}`1/api/v4/return/16567/transaction/185330Language: java
Name: Example request
Description:
[Warning: empty required content area]Response Object
1returnTransactionResponse {
2 amount (double),
3 cardType (string) = 'MASTERCARD', 'VISA', 'AMEX', 'DINERS',
4 createdOn (string),
5 currency (string) = 'AUD', 'NZD',
6 paymentMethod (string) = 'CREDITCARD', 'PAYPAL', 'GIFTVOUCHER', 'CASH', 'AFTERPAY',
7 paymentProvider (string) = 'CYBERSOURCE', 'GIVEX', 'PAYPAL', 'BRAINTREE', 'AFTERPAY',
8 status (string) = 'APPROVED', 'DECLINED', 'PROCESSING',
9 transactionCode (string),
10 transactionId (string),
11 transactionNote (string),
12 transactionRef (string),
13 transactionType (string) = 'PAYMENT', 'REFUND', 'MANUAL REFUND'
14}Language: java
Name: Response Object
Description:
[Warning: empty required content area]Example response
1{
2 "transactionId": "123",
3 "transactionRef" : "123",
4 "transactionType" : "REFUND",
5 "transactionCode" : null,
6 "amount" : 0.1,
7 "currency" : "AUD",
8 "paymentProvider": "PAYPAL",
9 "paymentMethod" : "PAYPAL",
10 "cardType" : null,
11 "transactionNote" : "Huge Transaction",
12 "createdOn" : "2016-07-20T00:40:34.845+0000",
13 "status": "APPROVED"
14}Language: text
Name: Example response
Description:
[Warning: empty required content area]View all Return Transactions
Retrieve all transactions associated with a Return
GET:
`api/v4.1/return/{returnId}/transaction`Request Object
1returnTransactionRequest {
2
3 start (integer, optional),
4
5 count (integer, optional)
6}Language: java
Name: Return Transaction request
Description:
[Warning: empty required content area]Example request
1{
2 "start":"1",
3 "count":"10"
4 }Language: text
Name: Example request
Description:
[Warning: empty required content area]Response Object
1returnTransactionResponse {
2
3 count (integer),
4 retailerId (string),
5 returnId (string),
6 returnRef (string),
7 returnType (string),
8 start (integer),
9 total (integer),
10 transactions (array):[
11 {
12 amount (double),
13 cardType (string) = 'MASTERCARD', 'VISA', 'AMEX', 'DINERS',
14 createdOn (string),
15 currency (string) = 'AUD', 'NZD',
16 paymentMethod (string) = 'CREDITCARD', 'PAYPAL', 'GIFTVOUCHER', 'CASH', 'AFTERPAY',
17 paymentProvider (string) = 'CYBERSOURCE', 'GIVEX', 'PAYPAL', 'BRAINTREE', 'AFTERPAY',
18 status (string) = 'APPROVED', 'DECLINED', 'PROCESSING',
19 transactionCode (string),
20 transactionId (string),
21 transactionNote (string),
22 transactionRef (string),
23 transactionType (string) = 'PAYMENT', 'REFUND', 'MANUAL REFUND'
24 }
25 ]
26}Language: java
Name: Response object
Description:
[Warning: empty required content area]Example response
1{
2 "start": 1,
3 "count": 100,
4 "total": 1,
5 "retailerId": 333,
6 "returnRef": "1",
7 "returnType": "CUSTOMER_RETURN",
8 "returnId": 1,
9 "transactions": [
10 {
11 "transactionId": "123",
12 "transactionRef": "123",
13 "transactionType": "PAYMENT",
14 "transactionCode": null,
15 "amount": 0.1,
16 "currency": "AUD",
17 "paymentProvider": "PAYPAL",
18 "paymentMethod": "PAYPAL",
19 "cardType": null,
20 "transactionNote": "Huge Transaction",
21 "createdOn": "2016-07-20T00:40:34.845+0000",
22 "status": "APPROVED"
23 }
24 ]
25}Language: java
Name: Example response
Description:
[Warning: empty required content area]Update Return Transaction
Edit the Return Transaction information
PUT:
`/api/v4.1/return/{returnId}/transaction/{transaction id}`Request Object
1returnTransactionRequest {
2
3 paymentMethod (string, optional) = 'CREDITCARD', 'PAYPAL', 'GIFTVOUCHER', 'CASH', 'AFTERPAY',
4 status (string, optional) = 'APPROVED', 'DECLINED', 'PROCESSING',
5 transactionNote (string, optional),
6 transactionRef (string, optional)
7}Language: java
Name: Return Transaction request
Description:
[Warning: empty required content area]Example request
1{
2 "transactionRef" : "123",
3 "status" : "APPROVED",
4 "paymentMethod" : "PAYPAL",
5 "transactionNote" : "Huge Transaction"
6}Language: text
Name: Example request
Description:
[Warning: empty required content area]Response Object
1SuccessMessageResponse {
2
3 id (integer, optional)
4}Language: java
Name: Response object
Description:
[Warning: empty required content area]Example response
1{
2 "id":"427323"
3}Language: java
Name: Example response
Description:
[Warning: empty required content area]Response on Failures
NAME | TYPE | DESCRIPTION |
error | Array | Array of errors |
message | String | Additional information on the code Unauthorized | Bad Request | Forbidden | Not Found | Status 500 Error |
code | String | Status Code for the above messages 401 | 400 | 403 | 404 | 500 |
