Elastic Path Gateways API

openapi: 3.2.0
info:
  title: Payment Introduction Gateways API
  description: "Payments for orders are processed through a payment gateway. Composable Commerce offers integrations for a selection of payment gateway providers, or you can create your own integrations.\n\nPayment transactions are processed similarly for all gateways:\n\n1. A payment transaction is created and an attempt to pay is made.\n2. The transaction is forwarded to the third-party gateway specified by the customer.\n3. The payment is processed by the third-party gateway.\n\nPayment transactions are always processed outside of Composable Commerce for security reasons. Typically, you use a token rather than pass the card details directly. If, however, you want to pass the cart details directly to the third-party provider, Composable Commerce enforces the use of the secure HTTPS protocol. If the transaction is successful, a `200 OK` response is returned. Use the response (success or failure) to update the transaction, which automatically updates the order and payment statuses.\n\nA payment transaction can also be refunded. You can select which way you want to process refunds:\n\n- Mark as Refunded: You can use your payment gateway’s console to process a refund. Process the refund first in the payment gateway and then use the **Mark as Refunded** capability in Composable Commerce to complete the process.\n- Refund through Composable Commerce: Start a full or partial refund to a supported payment provider directly from Commerce Manager or the API. You still have the ability to mark as refunded for a pre-integrated gateway, such as Stripe.\n\n:::info\n\nFor nonce-based Authorize.net transactions, if a refund is requested before the transaction has settled (typically within 24 hours), the transaction will be voided instead of refunded. This behavior is specific to nonce-based payments.\n\n:::\n\n:::caution\n\nConfigure your store to use [Manual Gateway](/docs/api/payments/update-manual-gateway) to process payments if the order total is zero or the payment is through non-supported payment providers.\n\n:::\n\n### Order Status Workflow\n\nThe following image shows the workflow of the order status when you checkout a cart.\n\n![Order Workflow](/assets/Order-Workflow.png)\n\n### Summary of the Workflow\n\n1. [Checkout a cart](/docs/api/carts/checkout). When you checkout a cart, an unpaid order is returned.\n2. [Paying for an order](/docs/api/carts/payments). You can process the payment for an order through a payment gateway. You can pay for an order either using purchase payment method or authorize payment method.\n3. Confirm the order. Order confirmation might be required when you purchase or authorize a transaction. If you use a purchase method, the order is immediately confirmed. If you use authorize method, funds are captured later when an item is dispatched or restocked, and then the order is considered as complete. See [Capture a Transaction](https://elasticpath.dev/docs/commerce-cloud/payments/transactions/capture-a-transaction).\n4. [Fulfill, Refund or Cancel the paid order](/docs/api/carts/refund-a-transaction). The order is considered as fulfilled when it is shipped. You can cancel the order after the checkout or if the order is not fulfilled. You can also choose to refund a partial payment or full payment.\n5. (Optional) [Cancel a transaction](/docs/api/carts/cancel-a-transaction). You can cancel or void a pending or authorized transaction. The transaction can be canceled or voided when it is in pending and completed statuses. This works only for Stripe and PayPal and does not work for manual gateway.\n6. (Optional) [Anonymize an order](/docs/api/carts/anonymize-orders). You can anonymize an order when it is fulfilled, canceled, or fully refunded.\n\n### Split Payments\n\nSplit payments involve multiple payment sources for a single order, using externally authorized payments. For example, you can pay for an order using a gift card and a credit card. An order with multiple payment transactions can also be in multiple payment states depending on each transaction.\n\nTransactions for split payments are processed similarly for all gateways:\n\n1. A partial payment transaction is created and an attempt to pay the partial amount is made.\n2. The transaction for the specified amount is forwarded to the payment gateway specified by the customer.\n3. The partial payment is processed.\n4. Another partial payment transaction is created and an attempt to pay the remaining amount is made.\n5. Another transaction for the remaining amount is forwarded to the payment gateway specified by the customer.\n6. The payment is processed, paid, and complete. The payment status must show paid after the order is completed.\n\nYou can refund transactions for split payments. For more information about refund, see Refund a Payment.\n\nThe following scenarios show how a shopper can use multiple sources for split payment:\n\n- Gift card and credit card\n- Purchase order and credit card\n- Store credit and credit card\n- Employee dollars and credit card\n- Gift card and loyalty card\n- Loyalty card and wallet\n\nThe following image shows a workflow of the split payments.\n\n![Split Payments](/assets/split-payment-workflow.png)\n\nThe following table describes the payment and order statuses that you can see when an order is passed through multiple stages.\n\n| Payment Status   | Order Status | Inventory Status     | Description |\n|:-----------------|:-------------|:---------------------|:------------|\n| `partially_authorized` | `incomplete` |\tAllocated\t| Indicates that the payment is partially_authorized and the balance_owing value is greater than zero. In this case, one of the transactions is authorized and complete. |\n| `partially_paid`  | `incomplete` |Allocated |\tIndicates that the funds are captured but the balance_owing value is greater than zero. In this case, one of the transactions is captured or purchase is complete. |\n| `unpaid` | `incomplete` |\tNot Allocated |\tIndicates that the order does not have any complete payment transactions. In this case, all the transactions or any of the transactions can be still pending. |\n| `authorized`\t| `processing`\t| Allocated | \tIndicates that completed transactions cover the entire total amount for an order and at least one of the transactions is authorized. |\n| `paid` |\t`complete`\t| Allocated | Indicates that the order is complete and the amount for the order is fully paid when all authorized transactions are captured or purchase transactions are complete. |\n"
  contact:
    name: Elastic Path
    url: https://elasticpath.com
  version: 25.1125.6251808
servers:
- url: https://useast.api.elasticpath.com
  description: US East Production Server
  variables: {}
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
  variables: {}
security: []
tags:
- name: Gateways
paths:
  /v2/gateways:
    get:
      tags:
      - Gateways
      summary: Get all Gateways
      description: Retrieves all gateways.
      operationId: getAllGateways
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Response.Gateway'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/{gatewaySlug}:
    get:
      tags:
      - Gateways
      summary: Get a Gateway
      description: Retrieves the specified gateway.
      operationId: getAGateway
      parameters:
      - name: gatewaySlug
        in: path
        description: The slug of the gateway.
        required: true
        schema:
          type: string
          enum:
          - manual
          - braintree
          - stripe
          - stripe_payment_intents
          - elastic_path_payments_stripe
          - paypal_express_checkout
          - adyen
          - authorize_net
          - card_connect
          - cyber_source
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      $ref: '#/components/schemas/Response.Gateway'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/manual:
    put:
      tags:
      - Gateways
      summary: Update Manual Gateway
      description: This endpoint allows you update the manual gateway.
      operationId: updateManualGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Request.UpdateManualGateway'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    enabled: true
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      properties:
                        enabled:
                          description: Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.
                          example: true
                          type: boolean
                        name:
                          description: Specifies the nme of the gateway.
                          example: Manual
                          type: string
                        slug:
                          description: Specifies the slug of the gateway.
                          example: manual
                          type: string
                        type:
                          description: Specifies the type of object being returned.
                          example: gateway
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/braintree:
    put:
      tags:
      - Gateways
      summary: Update Braintree Gateway
      description: Use this endpoint to configure Braintree.
      operationId: updateBraintreeGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Request.UpdateBraintreeGateway'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    enabled: true
                    environment: sandbox
                    merchant_id: '{{braintreeMerchantId}}'
                    private_key: '{{braintreePrivateKey}}'
                    public_key: '{{braintreePublicKey}}'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      properties:
                        enabled:
                          description: Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.
                          example: true
                          type: boolean
                        name:
                          description: Specifies the name of the gateway.
                          example: Braintree
                          type: string
                        environment:
                          description: Specifies production or sandbox environment.
                          example: sandbox
                          type: string
                        merchant_id:
                          description: Specifies Your Braintree merchant ID.
                          example: '{{braintreeMerchantId}}'
                          type: string
                        private_key:
                          description: Represents Your Braintree private key.
                          example: '{{braintreePrivateKey}}'
                          type: string
                        public_key:
                          description: Indicates Your Braintree public key.
                          example: '{{braintreePublicKey}}'
                          type: string
                        slug:
                          description: Represents the slug of the gateway.
                          example: braintree
                          type: string
                        type:
                          description: Specifies the type of object being returned.
                          example: gateway
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/stripe:
    put:
      tags:
      - Gateways
      summary: Update Stripe Gateway
      description: Use this endpoint to configure Stripe.
      operationId: updateStripeGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Request.UpdateStripeGateway'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    enabled: true
                    login: '{{stripeToken}}'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      properties:
                        enabled:
                          description: Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.
                          example: true
                          type: boolean
                        login:
                          description: Represents Stripe test or live secret key.
                          example: '{{stripeToken}}'
                          type: string
                        name:
                          description: Specifies the name of the gateway.
                          example: Stripe
                          type: string
                        slug:
                          description: Represents the slug of the gateway.
                          example: stripe
                          type: string
                        type:
                          description: Specifies the type of object being returned.
                          example: gateway
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/stripe_payment_intents:
    put:
      tags:
      - Gateways
      summary: Update Stripe Payment Intents Gateway
      description: Use this endpoint to configure Stripe Payment Intents.
      operationId: updateStripeIntentsGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Request.UpdateStripeGateway'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    enabled: true
                    login: '{{stripeLoginToken}}'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      properties:
                        enabled:
                          description: Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.
                          example: true
                          type: boolean
                        login:
                          description: Specifies the Stripe secret key for your account that is in live or test mode.
                          example: '{{stripeLoginToken}}'
                          type: string
                        name:
                          description: Specifies the name of the gateway.
                          example: Stripe Payment Intents
                          type: string
                        slug:
                          description: Represents the slug of the gateway.
                          example: stripe_payment_intents
                          type: string
                        type:
                          description: Specifies the type of object being returned.
                          example: gateway
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/elastic_path_payments_stripe:
    put:
      tags:
      - Gateways
      summary: Update Elastic Path Payments Powered by Stripe
      description: "Use this endpoint to configure Elastic Path Payments Powered by Stripe in Commerce. \n\n:::note\n\nYou can contact Elastic Path sales or [customer success team](mailto:customersuccess@elasticpath.com) to get more information about Elastic Path Payments Powered by Stripe and to check whether it will work for you.\n\n:::\n"
      operationId: updateEpPaymentsStripe
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Request.UpdateElasticPathPaymentsStripeGateway'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    enabled: true
                    stripe_account: '{{stripeAccountId}}'
                    test: true
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      properties:
                        enabled:
                          description: Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.
                          example: true
                          type: boolean
                        stripe_account:
                          description: Specifies the Stripe account ID.
                          example: '{{stripeAccountId}}'
                          type: string
                        name:
                          description: Specifies the name of the gateway.
                          example: Elastic Path Payments powered by Stripe
                          type: string
                        test:
                          description: Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.
                          example: true
                          type: boolean
                        slug:
                          description: Represents the slug of the gateway.
                          example: elastic_path_payments_stripe
                          type: string
                        type:
                          description: Specifies the type of object being returned.
                          example: gateway
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/paypal_express_checkout:
    put:
      tags:
      - Gateways
      summary: Update PayPal Express Checkout
      description: "Use this endpoint to configure PayPal Express Checkout. \n:::note\n\nTo learn more about PayPal Express Checkout and check whether it will work for you, contact your sales or [customer success team](mailto:customersuccess@elasticpath.com).\n\n:::\n"
      operationId: updatePaypalExpressCheckoutGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Request.UpdatePaypalExpressCheckoutGateway'
              contentMediaType: application/json
            examples:
              default:
                value:
                  data:
                    enabled: true
                    payer_id: '{{merchant account id}}'
                    test: true
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      properties:
                        enabled:
                          description: Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.
                          example: true
                          type: boolean
                        payer_id:
                          description: Specifies the merchant account ID. The ID is displayed in the PayPal account details of the merchant.
                          example: '{{merchant account id}}'
                          type: string
                        name:
                          description: Specifies the name of the gateway.
                          example: PayPal Express Checkout
                          type: string
                        test:
                          description: Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.
                          example: true
                          type: boolean
                        slug:
                          description: Represents the slug of the gateway.
                          example: paypal_express_checkout
                          type: string
                        type:
                          description: Specifies the type of object being returned.
                          example: gateway
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/adyen:
    put:
      tags:
      - Gateways
      summary: Update Adyen Gateway
      description: Use this endpoint to configure Adyen.
      operationId: updateAdyenGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdyenGatewayRequest'
            examples:
              default:
                value:
                  data:
                    enabled: true
                    merchant_account: MyCompanyECOM
                    username: ws@Company.MyCompany
                    password: xxx
                    test: false
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      allOf:
                      - $ref: '#/components/schemas/Response.Gateway'
                      - properties:
                          merchant_account:
                            description: Represents your Adyen merchant account code. For example, MyCompanyECOM.
                            type: string
                            example: MyCompanyECOM
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/authorize_net:
    put:
      tags:
      - Gateways
      summary: Update Authorize.net Gateway
      description: '

        Use this endpoint to configure Authorize.net.


        :::note

        The credentials used for a test account may differ from those used for a live account. When configuring the payment gateway with your credentials and setting `test` to `true`, the system allows you to test various Authorize.net payment interactions to ensure everything works as expected. Once you are ready to go live, update `test` as `false` to direct requests to the live endpoints instead of the test account. Additionally, ensure that you switch to the credentials for the live account when making this change. To access your sandbox environment, see [Authorize.net Sandbox account](https://developer.authorize.net/hello_world/sandbox.html).

        :::

        '
      operationId: updateAuthorizeNetGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Request.UpdateAuthorizeNetGateway'
            examples:
              default:
                value:
                  data:
                    login: xxx
                    password: xxx
                    slug: authorize_net
                    enabled: true
                    test: true
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      allOf:
                      - $ref: '#/components/schemas/Response.Gateway'
                      - properties:
                          password:
                            description: Indicates Authorize.net Transaction Key.
                            type: string
                            example: authorize-net-transaction-key
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/card_connect:
    put:
      tags:
      - Gateways
      summary: Update CardConnect Gateway
      description: Use this endpoint to configure CardConnect.
      operationId: updateCardConnectGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request.UpdateCardConnectGateway'
            examples:
              default:
                value:
                  data:
                    merchant_id: xxx
                    username: xxx
                    password: xxx
                    test: false
                    enabled: false
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      allOf:
                      - $ref: '#/components/schemas/Response.Gateway'
                      - properties:
                          merchant_id:
                            description: Specifies your CardConnect Merchant ID.
                            type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  status: 401
                  title: Unauthorized
      deprecated: false
  /v2/gateways/cyber_source:
    put:
      tags:
      - Gateways
      summary: Update CyberSource Gateway
      description: Use this endpoint to configure CyberSource.
      operationId: updateCyberSourceGateway
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request.UpdateCyberSourceGateway'
            examples:
              default:
                value:
                  data:
                    enabled: true
                    login: xxx
                    password: xxx
                    test: true
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - properties:
                    data:
                      type: object
                      allOf:
                      - $ref: '#/components/schemas/Response.Gateway'
                      - properties:
                          login:
                            description: Represents your live or test CyberSource merchant ID.
                            type: string
                            example: cybersource-merchant-id
                          password:
                     

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-gateways-api-openapi.yml