Payment-Refund-v2: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
(Created page with "{{PageTitle|title=Barion API: Execute the refund of a payment}} {| style="margin-left:2em;" align="right" | __TOC__ |} {{api_callmethod |method=GET |uri=/v2/Payment/Refund }...")
 
m (replaced reference to v2 GetPaymentState with v4 PaymentState)
 
(14 intermediate revisions by 3 users not shown)
Line 6: Line 6:


{{api_callmethod
{{api_callmethod
|method=GET
|method=POST
|uri=/v2/Payment/Refund
|uri=/v2/Payment/Refund
}}
}}
Line 13: Line 13:


Prerequisites before use:
Prerequisites before use:
* [[Integrating the Barion Smart Gateway]]
* [[Creating_an_account|Creating an account in Barion]]
* [[Registering your shop in Barion]]
* [[Creating_a_shop|Creating a shop in Barion]]
* [[Calling the Barion API]]
* [[Calling_the_API|Calling the Barion API]]
* API: [[Payment-Start-v2 | /Payment/Start]]
* API: [[Payment-Start-v2 | /Payment/Start]]
* API: [[Payment-GetPaymentState-v2 | /Payment/GetPaymentState]]
* API: [[Payment-PaymentState-v4 | /Payment/<PaymentId>/PaymentState]]
 


<span class="api-ver">v2</span> This API endpoint is available in '''API v2''' only.
<span class="api-ver">v2</span> This API endpoint is available in '''API v2''' only.


= Use cases =
== Authentication ==
 
[[Barion Shop Authentication]]
 
== Use cases ==


This API endpoint is designed to be used in the following scenarios:
This API endpoint is designed to be used in the following scenarios:
* [[Simple-Webshop-Integration|Simple Webshop Integration]]
* [[Responsive_web_payment|Responsive Web Payment]]


= Input properties =
== Input properties ==


{{api_input_table_header}}
{{api_input_table_header}}
Line 39: Line 44:
* Required
* Required
|| The identifier of the payment in the Barion system.
|| The identifier of the payment in the Barion system.
|-
| TransactionsToRefund || [[TransactionToRefund]][] ||
* Required
|| An array containing the payment transactions to refund.


|}
|}


= Output properties =
== Output properties ==


{{api_output_table_header}}
{{api_output_table_header}}
Line 50: Line 61:
|-
|-


| PaymentRequestId || string || The identifier of the payment in the shop's system.
| RefundedTransactions || [[RefundedTransaction]][] || An array containing information about the refunded transactions.


|-
|}


| POSId || Guid || The public identifier of the shop that created the payment.
== Possible error responses  ==


{| class="wikitable api-table"
! Error code || Description
|-
|-
 
| ModelValidationError || This happens when some of the input properties fail the basic validation. For example a string property exceeds its allowed length.
| POSName || string || The name of the shop that created the payment.
 
|-
|-
 
| NotExistingPaymentId || The specified payment id is invalid.
| POSOwnerEmail || string || The e-mail address of the owner of the shop that created the payment.
 
|-
|-
 
| SuspendedUserTriedToRefund || You are not allowed to refund a payment if you are suspended.
| Status || [[PaymentStatus]] || The current status of the payment in the Barion system.
 
|-
|-
 
| TheSourceAndDestinationAccountsAreMatched || Very rare error, this happens in case the payment was payed by the shop owner.
| PaymentType || string || The type of the payment. Can be <code>Immediate</code> or <code>Reservation</code>.
 
|-
|-
 
| PaymentStatusNotValid || Only payments in <code>Succeeded</code> [[PaymentStatus|status]] can be refunded.
| AllowedFundingSources || string[] || The allowed funding sources that were defined when creating the payment.
 
|-
|-
 
| TransactionDoesNotBelongToPayment || The transaction specified in the request body does not belong to a payment.
| FundingSource || string || The funding source that was used to complete the payment. If the payment is not yet completed, this is empty.
|-
 
| InvalidTransactionType || The transaction specified is not a refundable [[TransactionType|transaction type]]. Only <code>CardPayment</code>, <code>Shop</code> and <code>BankTransferPayment</code> types are refundable.
|-
|-
 
| InvalidAccount || The account is not eligable for refund.
| FundingInformation || [[FundingInformation]] || Detailed information about the funding source that was used to complete the payment. If the payment is not yet completed, this is empty.
|-
 
| TooLowBalanceToMakeRefund || There is not enough funds to fulfill the refund request.
|-
|-
 
| AmountToRefundIsGreaterThanTransactionAmount || The amount specified to refund is greater than the original payment transaction itself.
| GuestCheckout || bool || Indicates wether the payment allows guest checkout.
|-  
 
| InternalServerError || Something unexpected happened.
|-
|-  
 
| CreatedAt || DateTime || The timestamp showing when the payment was created.
 
|-
 
| StartedAt || DateTime || The timestamp showing when a reservation payment was started. If the payment type is not reservation, this is empty.
 
|-
 
| CompletedAt || DateTime || The timestamp showing when the payment was completed. If the payment is not yet completed, this is empty.
 
|-
 
| ValidUntil || DateTime || Timestamp showing the expiration time of the payment time window. The payment must be completed before this elapses.
 
|-
 
| ReservedUntil || DateTime || Timestamp showing the expiration time of the reservation time window. The reserved payment must be finished before this elapses. If the payment type is not reservation, this is empty.
 
|-
 
| Transactions || [[DetailedPaymentTransaction]][] || An array containing a detailed structure of all transactions associated with the payment.
 
|-
 
| Total || decimal || The total amount of the payment <u>at the time of the request</u>. If a reservation was finished with a lower amount, or a previously completed payment was refunded, this can be less than at the time of creation.
 
|-
 
| Currency || string || The 3 character ISO 4217 currency code of the payment.
 
|-
 
| SuggestedLocale || string || Indicates in which language the Barion Smart Gateway should be shown for the payer.
 
|-
 
| FraudRiskScore || int || A risk score computed by the anti-fraud analysis, between a range of 0 (completely legit) to 100 (certain fraud).
 
|-
 
| CallbackUrl || string || The URL (including the payment identifier) where the Barion system will send (or already sent) a request to whenever there is a change in the state of the payment.
 
|-
 
| RedirectUrl || string|| The URL (including the payment identifier) where the payer gets (or already got) redirected to after the payment is or was completed or cancelled.
 
|}
|}

Latest revision as of 10:09, 25 March 2024

Barion API: Execute the refund of a payment

POST /v2/Payment/Refund

The /payment/refund API endpoint is used to execute a refund of an existing, completed payment.

Prerequisites before use:


v2 This API endpoint is available in API v2 only.

Authentication

Barion Shop Authentication

Use cases

This API endpoint is designed to be used in the following scenarios:

Input properties

Property name Property type Limitations and constraints Description
POSKey Guid
  • Required
The secret API key of the shop, generated by Barion. This lets the shop to authenticate through the Barion API, but does not provide access to the account owning the shop itself.
PaymentId Guid
  • Required
The identifier of the payment in the Barion system.
TransactionsToRefund TransactionToRefund[]
  • Required
An array containing the payment transactions to refund.

Output properties

Property name Property type Description
PaymentId Guid The identifier of the payment in the Barion system.
RefundedTransactions RefundedTransaction[] An array containing information about the refunded transactions.

Possible error responses

Error code Description
ModelValidationError This happens when some of the input properties fail the basic validation. For example a string property exceeds its allowed length.
NotExistingPaymentId The specified payment id is invalid.
SuspendedUserTriedToRefund You are not allowed to refund a payment if you are suspended.
TheSourceAndDestinationAccountsAreMatched Very rare error, this happens in case the payment was payed by the shop owner.
PaymentStatusNotValid Only payments in Succeeded status can be refunded.
TransactionDoesNotBelongToPayment The transaction specified in the request body does not belong to a payment.
InvalidTransactionType The transaction specified is not a refundable transaction type. Only CardPayment, Shop and BankTransferPayment types are refundable.
InvalidAccount The account is not eligable for refund.
TooLowBalanceToMakeRefund There is not enough funds to fulfill the refund request.
AmountToRefundIsGreaterThanTransactionAmount The amount specified to refund is greater than the original payment transaction itself.
InternalServerError Something unexpected happened.