Reusing the payment source

How to save the payment source into the customer wallet so that it can be reused

Problem

You want to save an external payment source already used to complete a purchase into the customer wallet and eventually reuse it for future payments.

Solution

1. To save the payment source into the customer wallet you have to send a PATCH request to the /api/orders/:id endpoint, setting the _save_payment_source_to_customer_wallet attribute to true.

2. To reuse the stored payment source you need to associate it with the related order. To do that send a PATCH request to the /api/orders/:id endpoint, using the ID of the selected customer payment source to properly set the _customer_payment_source_id attribute.

A call to the token_url endpoint you've specified when configuring your external payment gateway is performed in order to fetch the customer_token and the payment_source_token attributes. Please check the related guide for more details.

To get a list of the customer's available payment sources, include the available_customer_payment_sourcesrelationship in the request (1).

Example

1. Save the payment source into the customer wallet

Request

The following request save the external payment source to the customer wallet for the order identified by the "qaMAhZkZvd" ID:

curl -g -X PATCH \
  'http://yourdomain.commercelayer.io/api/orders/qaMAhZkZvd?include=available_customer_payment_sources' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "orders",
    "id": "qaMAhZkZvd",
    "attributes": {
      "_save_payment_source_to_customer_wallet": true
    }
  }
}'

Response

On success, the API responds with a 200 OK status code, returning the updated order object:

{
  "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": {...}
      },
      "available_customer_payment_sources": {
        "links": {...},
        "data": [
          {
            "type": "customer_payment_sources",
            "id": "QgDXpwsqDx"
          }
        ]
      },
      "payment_method": {
        "links": {...}
      },
      "payment_source": {
        "links": {...}
      },
      "line_items": {
        "links": {...}
      },
      "shipments": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
    {
      "id": "QgDXpwsqDx",
      "type": "customer_payment_sources",
      "links": {
          "self": "https://yourdomain.commercelayer.io/api/customer_payment_sources/QgDXpwsqDx"
      },
      "attributes": {
        "customer_token": "1",
        "name": "XXXX-XXXX-XXXX-1111",
        "payment_source_token": "7RxGd2HUyY1Yc2Tghw5N453piFs",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "customer": {
          "links": {...}
        },
        "payment_source": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ]
}

2. Reuse the payment source stored in the customer wallet

Request

The following request associates the payment source saved into the customer wallet and identified by the ID "QgDXpwsqDx" with the order identified by the "qaMAhZkZvd" ID:

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

Response

On success, the API responds with a 200 OK status code, returning the updated order object:

{
  "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": {...}
      },
      "available_customer_payment_sources": {
        "links": {...}
      },
      "payment_method": {
        "links": {...}
      },
      "payment_source": {
        "links": {...}
      },
      "line_items": {
        "links": {...}
      },
      "shipments": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

More to read

See our documentation if you need more information on how to update an order or deal with customer payment sources.