# Adding the payment source

## Problem

You have a pending order with a selected payment method that is associated with a Stripe payment integration. You want to give your customer the possibility to select one of the payment sources available from that gateway — e.g. a credit card — and use it to process the payment.

## Solution

To add a Stripe payment source to an order, you have to create a Stripe payment source object and associate it with the order, as described in the Checkout guide.

{% content-ref url="../../checkout/adding-a-payment-source" %}
[adding-a-payment-source](https://docs.commercelayer.io/how-tos/placing-orders/checkout/adding-a-payment-source)
{% endcontent-ref %}

### Example

#### 1. Get the payment source type

{% tabs %}
{% tab title="Request" %}
The following request retrieves the attributes of the payment method associated with the order identified by the "qaMAhZkZvd" ID:

```javascript
curl -g -X GET \
  'http://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd?include=payment_method' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the requested order object and the associated payment method:

```javascript
{
  "data": {
    "id": "qaMAhZkZvd",
    "type": "orders",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd"
    },
    "attributes": {...},
    "relationships": {
      "market": {
        "links": {...}
      },
      "customer": {
        "links": {...}
      },
      "shipping_address": {
        "links": {...}
      },
      "billing_address": {
        "links": {...}
      },
      "available_payment_methods": {
        "links": {...}
      },
      "payment_method": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd/relationships/payment_method",
          "related": "https://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd/payment_method"
        },
        "data": {
          "type": "payment_methods",
          "id": "WmOodsVPmQ"
        }
      },
      "payment_source": {
        "links": {...}
      },
      "line_items": {
        "links": {...}
      },
      "shipments": {
        "links": {...} 
      }
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
  {
      "id": "WmOodsVPmQ",
      "type": "payment_methods",
      "links": {...},
      "attributes": {
        "payment_source_type": "stripe_payments",
        "name": "Stripe Payment",
        "disabled_at": null,
        "price_amount_cents": 0,
        "price_amount_float": 0.0,
        "formatted_price_amount": "€0,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "",
        "reference_origin": "",
        "metadata": {}
      },
      "relationships": {
        "market": {
        "links": {...}
        },
        "payment_gateway": {
        "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

#### 2. Create the payment source and associate it with the order

{% tabs %}
{% tab title="Request" %}
The following request creates a Stripe payment object and associates it with the order identified by the "qaMAhZkZvd" ID:

```javascript
curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/stripe_payments' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "stripe_payments",
    "attributes": {},
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "qaMAhZkZvd"
        }
      }
    }
  }
}'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created Stripe payment object:

```javascript
{
  "data": {
    "id": "eqRZMSaNqM",
    "type": "stripe_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/stripe_payments/eqRZMSaNqM"
    },
    "attributes": {
      "client_secret": "xxxx_secret_yyyy",
      "publishable_key": "xxxx_secret_yyyy",
      "options": {},
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Additional notes

#### Client secret generation

At the moment of the Stripe payment source creation, a `PaymentIntent` object is created on the server-side — see [Stripe documentation](https://stripe.com/docs/api/payment_intents) for any reference. Its `client_secret` is returned in the related attribute of the response and can be used in your client to securely confirm the  `PaymentIntent` object and complete the payment workflow.

#### Asynchronous authorization

Stripe payments are **asynchronous**. When a Commerce Layer's `stripe_payment` is created and associated with an order, Stripe immediately creates a payment intent using the current order's `total_amount` as the `amount` to be authorized. Since the payment's authorization is based on a webhook, depending on your checkout implementation, two scenarios may occur:

1. the order is placed [before](#authorization-check-on-order-placement) the authorization is created
2. the order is placed [after](#payment-source-nullification) the authorization is created

#### Authorization check on order placement

To prevent any issues in case of an attempt to place the order **before** the authorization is created by the Stripe webhook we introduced a control on order placement to check if the payment has been authorized. If not, we automatically [refresh the payment source](https://docs.commercelayer.io/how-tos/placing-orders/payments/stripe/refreshing-the-payment-source) and try to force the authorization. In case, for any reason (e.g. the payment intent has not been confirmed client-side), the payment can't be authorized the order placement fails.

#### Payment source nullification

If a Stripe payment is authorized but the related order is not placed yet, the associated payment source cannot be changed. Anyway, if the order is placed **after** the authorization is created by the Stripe webhook there is a time interval where the order status is still *pending* and so the order is still editable (i.e. the customer can add or remove items from the cart, changing its amount). If this happens the order amount and the succeded authorization amount may differ, resulting in an error. To prevent that scenario, if the Stripe payment has no `options` defined, we try to update the payment intent to reflect the new amount. If that's not possible (or if `options` are present), the previously created Stripe's payment sources are nullified in case of order edit/refresh (or if the payment method associated with the order is changed) and must be recreated. In this case, if the payment has already been authorized, the related authorization is voided and the order's payment status is set back from *authorized* to *paid*.

{% hint style="info" %}
In view of this, make sure to set the payment source as **the last step** of your checkout implementation.
{% endhint %}

In some special cases (e.g. to give the user the possibility to change previously inserted credit card details) you may want to force the payment source nullification, even if the order has not been edited/refreshed and/or the related payment is already authorized. To do that, you can leverage the `_nullify_payment_source` attribute of the order and manually trigger the payment source nullification, along with the related authorization void (if any) and payment status reset.

## More to read

See our documentation if you need more information on how to [retrieve an order](https://docs.commercelayer.io/developers/v/api-reference/orders/retrieve), [include associations](https://docs.commercelayer.io/developers/including-associations), [create](https://docs.commercelayer.io/developers/v/api-reference/stripe_payments/create) or [update a Stripe payment](https://docs.commercelayer.io/developers/v/api-reference/stripe_payments/update). See our Checkout guide for more details on how to place an order.

{% content-ref url="../../checkout/placing-the-order" %}
[placing-the-order](https://docs.commercelayer.io/how-tos/placing-orders/checkout/placing-the-order)
{% endcontent-ref %}