Skip to content

Commit f570381

Browse files
bc-afengbc-afeng
authored
feat(payment): PAYMENTS-11030 Add documentation for transactions API endpoints (#1238)
<!-- Ticket number or summary of work --> # [PAYMENTS-11030] ## What changed? <!-- Provide a bulleted list in the present tense --> - Added new documentation page for the Transactions API - Documents prerequisites for provider configuration before creating transactions ## Release notes draft <!-- Provide an entry for the release notes using simple, conversational language. Don't be too technical. Explain how the change will benefit the merchant and link to the feature. Examples: * The newly-released [X feature] is now available to use. Now, you’ll be able to [perform Y action]. * We're happy to announce [X feature], which can help you [perform Y action]. * [X feature] helps you to create [Y response] using the [Z query parameter]. Now, you can deliver [ex, localized shopping experiences for your customers]. * Fixed a bug in the [X endpoint]. Now the [Y field] will appear when you click [Z option]. --> * You can now record payments processed outside of BigCommerce directly in your store using the new Transactions API. This is helpful if you're using an external payment system but still want to manage captures, voids, and refunds from within BigCommerce. ## Anything else? <!-- Add related PRs, salient notes, additional ticket numbers, etc. --> ping @bigcommerce/team-payments [PAYMENTS-11030]: https://bigcommercecloud.atlassian.net/browse/PAYMENTS-11030?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
1 parent de88f72 commit f570381

1 file changed

Lines changed: 109 additions & 0 deletions

File tree

‎docs/store-operations/payments/transactions.mdx‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Transactions API
3+
keywords: payments, transactions, authorization, purchase, capture, void, external payments
4+
---
5+
6+
# Transactions API
7+
8+
The Transactions API allows you to create transaction records in BigCommerce for payments that were processed externally. This enables merchants to use BigCommerce for post-order actions such as capture, void, and refund on transactions that originated outside of BigCommerce.
9+
10+
## Supported providers
11+
12+
Initially, this API supports importing transactions from the following payment providers:
13+
- Adyen
14+
- Authorize.net
15+
- Braintree
16+
- PayPal Commerce Platform
17+
- Stripe
18+
19+
Before using this API, these providers must first be configured on the merchant's store using the same credentials as those being used to process payments externally.
20+
21+
## Supported payment methods
22+
23+
The following payment methods are supported:
24+
- ACH (Adyen, Braintree, PayPal Commerce Platform, and Stripe only)
25+
- Apple Pay
26+
- Credit Card
27+
- Google Pay
28+
- iDEAL
29+
- PayPal (Braintree and PayPal Commerce Platform only)
30+
31+
## Prerequisites
32+
33+
To perform post-order actions such as capture or void on a transaction, the payment provider used to process the payment outside of BigCommerce must already be configured within BigCommerce at the time the transaction is created. The payment provider must be enabled and configured with the same channel and currency that the order is placed against.
34+
35+
This is because the payment provider ID is stored against the transaction at time of creation.
36+
37+
<Callout type="warning">
38+
#### Provider configuration required
39+
If the payment provider is not configured in BigCommerce when the transaction is created, no provider ID will be stored against the transaction. This means BigCommerce will not know which provider to call when attempting to capture or void the transaction.
40+
</Callout>
41+
42+
### Example scenario
43+
44+
Consider the following scenario:
45+
46+
1. A payment is authorized externally through Stripe.
47+
2. The transaction is POSTed to BigCommerce using the `/v3/payments/transactions/authorizations` endpoint.
48+
3. Stripe is **not yet configured** within BigCommerce for the currency and channel the order was created against.
49+
50+
In this case, when an attempt is made to capture the authorized transaction within BigCommerce, BigCommerce does not know which provider to call to capture the transaction.
51+
52+
## Endpoints
53+
54+
Individual endpoints are available for creating single transactions:
55+
56+
| Endpoint | Description |
57+
|----------|-------------|
58+
| `POST /v3/payments/transactions/authorizations` | Create an authorization transaction |
59+
| `POST /v3/payments/transactions/purchases` | Create a purchase transaction |
60+
61+
<Callout type="info">
62+
#### Future endpoints
63+
The following endpoints are planned for future phases:
64+
- `/v3/payments/transactions/captures`
65+
- `/v3/payments/transactions/voids`
66+
- `/v3/payments/transactions/refunds`
67+
</Callout>
68+
69+
## Batch processing
70+
71+
These endpoints do not currently support batch processing. Support for batch processing may be provided in a future phase.
72+
73+
## Security
74+
75+
These endpoints are secured in the same way as other BigCommerce REST endpoints as described in [Authentication](/docs/start/authentication).
76+
77+
<Callout type="info">
78+
#### Required OAuth scopes
79+
The OAuth2 scope required for these endpoints is `store_v2_transactions`, which is the same as the modify scope of `/v3/orders/{order_id}/transactions`.
80+
81+
This scope can be granted when creating a store-level API account in the control panel.
82+
</Callout>
83+
84+
## Payload notes
85+
86+
### AVS and CVV results
87+
88+
The `avs_result` and `cvv_result` fields must either:
89+
- Be omitted entirely
90+
- Be `null`
91+
- Have all property values (such as `code` and `message`) set to `null`
92+
93+
### Provider data
94+
95+
The `provider_data` field varies by provider and payment instrument. Accepted keys are filtered server-side based on the provider.
96+
97+
For example, depending on the payment instrument, the `provider_data` keys for Stripe might include:
98+
- `mandate_method_id`
99+
- `override_method_id`
100+
101+
## Related resources
102+
103+
### Endpoints
104+
- [Create Authorization Transaction](/docs/rest-payments/transactions#create-authorization-transaction)
105+
- [Create Purchase Transaction](/docs/rest-payments/transactions#create-purchase-transaction)
106+
107+
### Articles
108+
- [Payments API](/docs/store-operations/payments)
109+
- [Available Payment Gateways (Help Center)](https://support.bigcommerce.com/s/article/Available-Payment-Gateways)

0 commit comments

Comments
 (0)