Payment-PaymentState-v4: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
VisualWikitext
m (link with authentication info now points to the shop auth page itself (after that's been reworked))
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{PageTitle|title=Barion API: Request the details of a payment}}
{{PageTitle|title=Barion API: Request the current state of a payment}}


{| style="margin-left:2em;" align="right"
{| style="margin-left:2em;" align="right"
Line 7: Line 7:
{{api_callmethod
{{api_callmethod
|method=GET
|method=GET
|uri=/v4/payment/<PaymentId>/details
|uri=/v4/payment/<PaymentId>/paymentstate
}}
}}


The <code>/payment/details</code> API endpoint is used to query the details and current state of a given payment.
The <code>/payment/paymentstate</code> API endpoint is used to query the details and current state of a given payment.


Prerequisites before use:
Prerequisites before use:
Line 21: Line 21:
<span class="api-ver">v4</span> This API endpoint is available in '''API v4''' only.
<span class="api-ver">v4</span> This API endpoint is available in '''API v4''' only.


{{NotificationBox|title=WARNING|text=This API endpoint is NOT live yet!|color=#FF7A3D}}
{{NotificationBox|title=NOTE|text=This is the preferred API endpoint for querying the state of a payment.|color=#038Ed3}}
 
== Authentication ==
 
[[Barion Shop Authentication]]


== Use cases ==
== Use cases ==
Line 31: Line 27:
This API endpoint is designed to be used in the following scenarios:
This API endpoint is designed to be used in the following scenarios:
* [[Responsive_web_payment|Responsive Web Payment]]
* [[Responsive_web_payment|Responsive Web Payment]]
== Authentication ==
Use [[Barion Shop Authentication|header-based shop authentication]] when using the endpoint.


== Header variables ==
== Header variables ==
Line 36: Line 35:
{{api_input_table_header}}
{{api_input_table_header}}
|-
|-
| POSKey || Guid ||  
| x-pos-key || Guid ||  
* Required
* 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.
|| The secret API key of the shop, generated by Barion. Used to authenticate the shop in the Barion API, but does not provide access to the account itself that owns the shop.


|}
|}
Line 53: Line 52:
|}
|}


'''Example:''' <code><nowiki>GET https://api.barion.com/payment/f28b2b2572644d1084bbb3a7d8362337/details?poskey=43683c0247874c1eabad9f1616fae165</nowiki></code>
'''Example:''' <code>GET <nowiki>https://api.barion.com/v4/payment/f28b2b2572644d1084bbb3a7d8362337/paymentstate</nowiki></code>


== Output properties ==
== Output properties ==
Line 95: Line 94:
|-
|-


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


|-
|-
Line 114: Line 113:
|-
|-


| CreatedAt || DateTime || The timestamp showing when the payment was created.
| CreatedAt || DateTime || The locale-specific payment creation timestamp.


|-
|-


| CompletedAt || DateTime || The timestamp showing when the payment was completed. If the payment is not yet completed, this is empty.
| CompletedAt || DateTime || The locale-specific payment completion timestamp. 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.
| ValidUntil || DateTime || The payment must be completed before this locale-specific payment expiration timestamp.


|-
|-


| 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 || If the payment is a reservation, the shop's owner has until this locale-specific expiration timestamp to finish it. If the payment isn't a 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.
| DelayedCaptureUntil || DateTime || If the payment is a delayed capture, the shop owner has until this locale-specific expiration timestamp to capture it. If the payment isn't a delayed capture, this is empty.


|-
|-
Line 138: Line 137:
|-
|-


| 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.
| Total || decimal || The total amount of the payment <u>at the time of the request to the endpoint</u>. If a reservation was finished with a lower amount, or if the transaction is a refund of a previously completed payment, this can be lower than at payment creation time.


|-
|-


| Currency || string || The 3 character ISO 4217 currency code of the payment.
| Currency || string || The payment's 3-character ISO 4217 currency code.


|-
|-


| SuggestedLocale || string || Indicates in which language the Barion Smart Gateway should be shown for the payer.
| SuggestedLocale || string || Indicates the language that the Barion Smart Gateway should be displayed to 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.
| FraudRiskScore || int || A risk score computed by the anti-fraud analysis, ranging from 0 (completely legit) to 100 (certain fraud). Transactions below a fraud risk score of 10 are usually safe. Transactions between 10 and 30 are risky, caution is advised. Transactions with a fraud risk score of 30 or above are blocked automatically to avoid 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.
| CallbackUrl || string || The URL (including the payment identifier) where the Barion system will send (or has 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.
| RedirectUrl || string|| The URL (including the payment identifier) where the payer gets (or has already got) redirected to after the payment is, or was completed, or cancelled.


|-
|-


| PaymentMethod || [[PaymentMethod]]|| The last method used when attempting to complete the payment. If there was no payment attempt made yet, this property is Unknown.
| PaymentMethod || [[PaymentMethod]]|| The last method used when attempting to complete the payment. If there was no payment attempt made yet, this property is <code>Unknown</code>.


|}
|}

Latest revision as of 18:10, 23 April 2024

Barion API: Request the current state of a payment

GET /v4/payment/<PaymentId>/paymentstate

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

Prerequisites before use:


v4 This API endpoint is available in API v4 only.

NOTE
This is the preferred API endpoint for querying the state of a payment.

Use cases

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

Authentication

Use header-based shop authentication when using the endpoint.

Header variables

Property name Property type Limitations and constraints Description
x-pos-key Guid
  • Required
 The secret API key of the shop, generated by Barion. Used to authenticate the shop in the Barion API, but does not provide access to the account itself that owns the shop.

Path variables

Property name Property type Limitations and constraints Description
PaymentId Guid
  • Required
 The identifier of the payment in the Barion system.

Example: GET https://api.barion.com/v4/payment/f28b2b2572644d1084bbb3a7d8362337/paymentstate

Output properties

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. Can be Balance, BankCard or BankTransfer. 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.
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 locale-specific payment creation timestamp.
CompletedAt DateTime The locale-specific payment completion timestamp. If the payment is not yet completed, this is empty.
ValidUntil DateTime The payment must be completed before this locale-specific payment expiration timestamp.
ReservedUntil DateTime If the payment is a reservation, the shop's owner has until this locale-specific expiration timestamp to finish it. If the payment isn't a reservation, this is empty.
DelayedCaptureUntil DateTime If the payment is a delayed capture, the shop owner has until this locale-specific expiration timestamp to capture it. If the payment isn't a delayed capture, 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 to the endpoint. If a reservation was finished with a lower amount, or if the transaction is a refund of a previously completed payment, this can be lower than at payment creation time.
Currency string The payment's 3-character ISO 4217 currency code.
SuggestedLocale string Indicates the language that the Barion Smart Gateway should be displayed to the payer.
FraudRiskScore int A risk score computed by the anti-fraud analysis, ranging from 0 (completely legit) to 100 (certain fraud). Transactions below a fraud risk score of 10 are usually safe. Transactions between 10 and 30 are risky, caution is advised. Transactions with a fraud risk score of 30 or above are blocked automatically to avoid fraud.
CallbackUrl string The URL (including the payment identifier) where the Barion system will send (or has 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 has already got) redirected to after the payment is, or was completed, or cancelled.
PaymentMethod PaymentMethod The last method used when attempting to complete the payment. If there was no payment attempt made yet, this property is Unknown.
Retrieved from "https://docs.barion.com/index.php?title=Payment-PaymentState-v4&oldid=4361"