Payment-GetPaymentState-v2: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
m (added deprecation note, with link to the v4)
 
(28 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{PageTitle|title=Barion API: Request the current state of a payment}}
{| style="margin-left:2em;" align="right"
{| style="margin-left:2em;" align="right"
| __TOC__
| __TOC__
|}
|}


= Barion API: Request the current state of a payment =
{{api_callmethod
{{api_callmethod
|method=GET
|method=GET
Line 12: 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]]


<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 ==  
{{NotificationBox|title=IMPORTANT|text=This endpoint is deprecated – use [[Payment-PaymentState-v4|the new v4 API endpoint]] instead whenever you can!|color=#FF7A3D}}
 
== 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 41: Line 51:


== Output properties ==
== Output properties ==
{{NotificationBox|title=IMPORTANT|text=This is a GET endpoint, parameters should be sent in the query string (eg. <nowiki> https://api.test.barion.com/v2/Payment/GetPaymentState?PosKey=xxx&PaymentId=yyy</nowiki>)!|color=#FF7A3D}}


{{api_output_table_header}}
{{api_output_table_header}}
Line 61: Line 73:


| POSOwnerEmail || string || The e-mail address of the owner of the shop that created the payment.
| POSOwnerEmail || string || The e-mail address of the owner of the shop that created the payment.
|-
| POSOwnerCountry || string || ISO2 country code of the owner of the shop that created the payment.


|-
|-
Line 68: Line 84:
|-
|-


| PaymentType || string || The type of the payment. Can be <code>Immediate</code> or <code>Reservation</code>.
| PaymentType || string || The type of the payment. Can be <code>Immediate</code>, <code>Reservation</code>, or <code>DelayedCapture</code>.


|-
|-
Line 76: Line 92:
|-
|-


| FundingSource || string || The funding source that was used to complete the payment. If the payment is not yet completed, this is empty.
| FundingSource || string || The funding source that was used to complete the payment. If the payment is not yet completed, this is empty. Can be <code>Balance</code>, <code>BankCard</code> or <code>BankTransfer</code>.


|-
|-


| 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.
| FundingInformation || [[FundingInformation]] || Detailed information about the funding source that was used to complete the payment. If no payment attempt was made, this is empty.


|-
|-


| GuestCheckout || bool || Indicates wether the payment allows guest checkout.
| RecurrenceType || [[RecurrenceType]] || The RecurrenceType that was defined in the payment/start request for the recurring scenario.


|-
|-


| CreatedAt || DateTime || The timestamp showing when the payment was created.
| TraceId || string || The Trace Id that identifies that recurring scenario. Read more about this [[Token_payment_3D_Secure|here]]


|-
|-
| GuestCheckout || bool || Indicates whether the payment allows guest checkout.


| StartedAt || DateTime || The timestamp showing when a reservation payment was started. If the payment type is not reservation, this is empty.
|-
 
| CreatedAt || DateTime || The timestamp showing when the payment was created.


|-
|-
Line 105: Line 124:


| 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.
| 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.
|-
| DelayedCaptureUntil || DateTime || Timestamp showing the expiration time of the authorization time window. The authorized payment must be finished before this elapses. If the payment type is not DelayedCapture, this is empty.


|-
|-
Line 124: Line 147:
|-
|-


| FraudRiskScore || int || A risk score computed by the anti-fraud analysis, between a range of 0 (completely legit) to 100 (certain fraud).
| FraudRiskScore || int || A risk score computed by the anti-fraud analysis, between a range of 0 (completely legit) to 100 (certain fraud). Transactions under 10 are usually safe. Transactions with 10 an more, but less than 30 are risky, caution is advised. Transactions with 30 and over are blocked automatically for being almost certainly fraudulent.


|-
|-

Latest revision as of 09:52, 25 March 2024

Barion API: Request the current state of a payment

GET /v2/Payment/GetPaymentState

The /payment/getpaymentstate API endpoint is used to query the details and current state of a given payment.

Prerequisites before use:


v2 This API endpoint is available in API v2 only.

IMPORTANT
This endpoint is deprecated – use the new v4 API endpoint instead whenever you can!

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.

Output properties

IMPORTANT
This is a GET endpoint, parameters should be sent in the query string (eg. https://api.test.barion.com/v2/Payment/GetPaymentState?PosKey=xxx&PaymentId=yyy)!
Property name Property type Description
PaymentId Guid The identifier of the payment in the Barion system.
PaymentRequestId string The identifier of the payment in the shop's system.
POSId Guid The public identifier of the shop that created the payment.
POSName string The name of the shop that created the payment.
POSOwnerEmail string The e-mail address of the owner of the shop that created the payment.
POSOwnerCountry string ISO2 country code of the owner of the shop that created the payment.
Status PaymentStatus The current status of the payment in the Barion system.
PaymentType string The type of the payment. Can be Immediate, Reservation, or DelayedCapture.
AllowedFundingSources string[] The allowed funding sources that were defined when creating the payment.
FundingSource string The funding source that was used to complete the payment. If the payment is not yet completed, this is empty. Can be Balance, BankCard or BankTransfer.
FundingInformation FundingInformation Detailed information about the funding source that was used to complete the payment. If no payment attempt was made, this is empty.
RecurrenceType RecurrenceType The RecurrenceType that was defined in the payment/start request for the recurring scenario.
TraceId string The Trace Id that identifies that recurring scenario. Read more about this here
GuestCheckout bool Indicates whether the payment allows guest checkout.
CreatedAt DateTime The timestamp showing when the payment was created.
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.
DelayedCaptureUntil DateTime Timestamp showing the expiration time of the authorization time window. The authorized payment must be finished before this elapses. If the payment type is not DelayedCapture, 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 at the time of the request. 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). Transactions under 10 are usually safe. Transactions with 10 an more, but less than 30 are risky, caution is advised. Transactions with 30 and over are blocked automatically for being almost certainly fraudulent.
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.