WARNING
Do not use the CANCEL OR REFUND service but the UPDATE ORDER service described in this chapter to proceed with the partial or total cancellation of an order.
It is possible to cancel an order totally or partially.
If the new amount of the order is inferior to the amount charged to the client, Floa will reimburse the client directly for the excess amount. Future installments will be canceled.
The cancellation is done by calling the UpdateOrder method.
RULES TO KNOW ABOUT CANCELLATIONS
- It is not possible to cancel an order dating back more than a year.
- It is not possible to partially cancel a 10X order.
- If a partial or a total cancellation occurs when an installment is being debited (between D-6 and D+1, D being the due date), the service will answer OK and the cancellation will only be processed on Floa side when the installment has been paid (i.e when the funds are captured).
- In the case of partial cancellation, Floa fees will not be refunded to the customer even if a second partial cancellation totally cancels the order.
- When you request the total or partial cancellation of an order, there is no way to cancel this cancellation request.
To make a refund, the following information must be available at the time of the request (i.e., this data must be stored in your system to be retrieved) :
- MerchantID
- MerchantSiteID
- ScoringToken
These data allow us to find the order reference in our system and to proceed with the cancellation/refund.
It is possible to make several successive partial cancellations for the same order.
Be careful when several calls to the UpdateOrder method are made for the same order, it is necessary to update the OldAmount field accordingly.
OldAmount is the amount of the order without fees. This is the amount you sent as input to the Eligibility method.
Call
The call must be made in POST REST, body in JSON
Calling URL :
- Integration : https://paymentservices.integration-cb4x.fr/MerchantGatewayFrontService.svc/UpdateOrder
- Production : https://paymentservices.cb4x.fr/MerchantGatewayFrontService.svc/UpdateOrder
Call Content :
| Field | Description | Type |
|---|---|---|
| headerMessage | Header | Node |
| Context | Context of the call | Node |
| MerchantId | Merchant ID | Integer(10) |
| MerchantSiteId | Merchant site ID | String |
| SecurityContext | Call security | Node |
| DomainRightsList | Not used in this context: put null | Node |
| IssuerID | Not used in this context: put null | String |
| SessionID | Not used in this context: put null | String |
| SubjectLocality | Not used in this context: put null | String |
| TokenId | Session token obtained when calling Authenticate | String |
| Localization | Location of the call | Node |
| Language | Language used | Enum |
| Currency | Currency used for the amount (=EUR) | Enum |
| Country | Country code | Enum |
| DecimalPosition | Position of the decimal separator (=2) | Integer |
| Version | Version of the payment platform used (=1.0) | string |
| updateOrderRequestMessage | Cancellation details | Node |
| OrderRef | Unique merchant reference order | String(30) |
| ScoringToken | Valid scoring token (returned by the Eligibility method) | String(30) |
| OldAmount | Old order amount in cents (without fees) Value presale_folder/raw_amount sent when calling Eligibility for a first-order cancellation | Integer |
| NewAmount | New order amount in cents. Must be less than OldAmount | Integer |
Example of a body (for a total cancellation) :
{
"headerMessage" : {
"Context" : {
"MerchantId" : 38,
"MerchantSiteId" : "7017"
},
"SecurityContext" : {
"DomainRightsList": null,
"IssuerID" : null,
"SessionID" : null,
"SubjectLocality" : null,
"TokenId" : "cce001dea981446bb2d18141015d3cad",
"UserName" : null
},
"Localization" : {
"Language": "FR",
"Currency" : "EUR",
"Country" : "FR",
"DecimalPosition" : 2
},
"Version" : "1.0"
},
"updateOrderRequestMessage" : {
"OrderRef" : "123",
"ScoringToken" : "365861cb35124911a56cb0cddc3d4176",
"OldAmount" : 12345,
"NewAmount" : 0
}
}
Response
| Name | Description | Type |
|---|---|---|
| OrderRef | Unique identifier that defines the customer's order. | string(30) |
| OrderTag | Not used | Null |
| MerchantId | Merchant ID | int |
| MerchantSiteId | Merchant's site identifier | string |
| ResponseCode | Code of the response | string |
| ResponseMessage | Messsage of the response | string |
| Schedule | Informations about the intallment | List of ScheduleItem |
For each installment (ScheduleItem)
| Name | Description |
|---|---|
| Rank | Number of the installment |
| ScheduleDate | Date |
| Amount | New amount |
| Exponent | 2 (Always 2) |
| Currency | 978 (=EUR) |
| Authority | 4 (Always 4) |
| State | New state 0 : TO CAPTURE (Installment to collect) 2 / 10 : PAYED (Installement collected) 4 : REFUSED (Debit refused) 5 : CANCELLED (Installment cancelled) |
| Transactions | Null |
| CapturedAmount | Amount captured |
| RemainingAmount | Amount to be captured |
| CancelledAmount | Amount cancelled (will not be captured) |
| RefundedAmount | Amount refunded to the customer |
Example of a response (for a partial cancellation) :
{
"UpdateOrderResult": {
"OrderRef": "1647963153",
"OrderTag": null,
"MerchantID": 38,
"MerchantSiteID": "7017",
"ResponseCode": 0,
"ResponseMessage": "Request was successfully processed",
"Schedule": [
{
"Rank": 1,
"ScheduleDate": "2022-03-22",
"Amount": 21849,
"Exponent": 2,
"Currency": 978,
"Authority": 4,
"State": 2,
"Transactions": null,
"CapturedAmount": 21849,
"RemainingAmount": 0,
"CancelledAmount": 0,
"RefundedAmount": 0
},
{
"Rank": 2,
"ScheduleDate": "2022-04-21",
"Amount": 116,
"Exponent": 2,
"Currency": 978,
"Authority": 4,
"State": 0,
"Transactions": null,
"CapturedAmount": 0,
"RemainingAmount": 116,
"CancelledAmount": 0,
"RefundedAmount": 0
},
{
"Rank": 3,
"ScheduleDate": "2022-05-21",
"Amount": 21848,
"Exponent": 2,
"Currency": 978,
"Authority": 4,
"State": 5,
"Transactions": null,
"CapturedAmount": 0,
"RemainingAmount": 0,
"CancelledAmount": 21848,
"RefundedAmount": 0
},
{
"Rank": 4,
"ScheduleDate": "2022-06-20",
"Amount": 21848,
"Exponent": 2,
"Currency": 978,
"Authority": 4,
"State": 5,
"Transactions": null,
"CapturedAmount": 0,
"RemainingAmount": 0,
"CancelledAmount": 21848,
"RefundedAmount": 0
}
]
}
}
Cancellation service return codes
- responseCode 0 or 4: the cancellation has been received by our service and should therefore be considered as OK on your side.
- responseCode 1 or 2: the cancellation is refused, there is no problem, it means that the cancellation can't be processed. To understand the refusal, it is possible to look at the responseMessage.
- response Code 3 or 5: technical error. The cancellation cannot be processed due to a technical problem. The responseMessage can help to understand where the problem lies.
Return messages from the cancellation service
| Code | Message | Description |
|---|---|---|
| 0 | Request was successfully processed | Successful cancellation |
| 0 | Schedule item is being processed. The request will be processed later | Request received, schedule will be updated later, no additional action required |
| 0 | Litigation with this order. Manual processing pending | Dispute with this order. The request is received and will be processed later, no further action required |
| 1 | Request could not be processed | An error has occurred in the processing of the cancellation. Contact Floa technical support |
| 1 | The order is too old, its amount cannot be updated anymore | The order is too old to be refunded with the UpdateOrder service. If you wish to reimburse the customer, the reimbursement will have to be made by your own means |
| 1 | New amount can't be bigger than old amount | The new order amount must be expressed in cents (without fees) in the NewAmount field and cannot be greater than the value in the OldAmount field (old order amount) |
| 1 | This order is not entitled to partial refund | Order is not eligible for a partial cancellation (10X order) |
| 1 | MerchantId or MerchantSiteId are invalid | Invalid MerchantId or MerchantSiteId |
| 1 | Old amount does not match the order amount | The old order amount must be expressed in cents (without fees) in the OldAmount field and must correspond to the remaining amount for the order |
| 1 | Invalid order ref : Unknow command | OrderRef invalid, order unknown |
| 1 | Merchant site identifier unknown | MerchantSiteId unknown |
| 1 | Merchant identifier unknown | MerchantId unknown |
| 1 | Missing merchant site identifier | MerchantSiteId is missing |
| 1 | Missing order reference | OrderRef is missing |
| 1 | Missing token ref | The scoring token corresponding to the order is missing |
| 1 | The new amount can't be lower than 0 | The new order amount (NewAmount field) cannot be less than 0 |
| 1 | No schedule is in pending | No payment schedule has been found for this order |
| 1 | The order has already been refunded | The order has already been canceled |
| 1 | The provided scoring token does not match the scoring token used for the order | Invalid scoring token, it does not match the token used for the order |
| 1 | No schedule item found | No installment found |
| 2 | Request could not be processed due to bank refusal | Refund refusal from the bank |
| 3 | Missing order schedule rank | Payment schedule does not exist for this order or this couple merchantId/merchantSiteId |
| 4 | Request will be processed later | Request taken into account, schedule will be updated later, no additional action required |
| 4 | Another Update Order Request is already running for the same order ref | Order cancellation is already in progress |
| 5 | Message depends on the technical error encoutered | An error occured in the processing of the cancellation. Contact Floa technical support |