Link Search Menu Expand Document

Registering a payment method is completely optional, as we allow the partners to take over payment method integration on their side and then create a monthly billing process between TIER and the partner.

Register a payment method for a customer

ℹ Note that the format of the payload changes for each individual payment provider and that the payload is not returned again after having created the payment method.

HTTP Request

POST https://platform.tier-services.io/v1/payment-method

Query Parameters

Parameter Description
provider The name of the payment provider to be used by that customer, see below.
customer The customer, identified by the UUID, e.g. {‘id’: }
payload The payment provider specific payload, see below.

Payment Providers and Payload format

Payment Provider Payload Format Description
LOGPAY {‘customerId’: }  
BRAINTREE {‘paypalNonce’: }  
STRIPE {‘token’: }   
curl "https://platform.tier-services.io/v1/payment-method"
  -X POST
  -H "x-api-key: TIER API KEY"
  -d '{
    "provider": "LOGPAY",
    "customer": {
      "id": "<uuid>"
    },
    "payload": {"customerId": <customerId>},
  }'
Click to expand JSON data response 
    {
      "data": {
            "id": "5fa6987a-85f9-49fe-85cb-a639f58a43b6",
            "type": "payment-method",
            "attributes": {
                "provider": "LOGPAY",
                "name": "A name that is visible to the user",
                "active": true,
                "brand": "Enum value for CC brand or 'Unknown'"
            },
            "relationships": {
              "customer": {
                "type": "customer",
                "id": "092bd178-25a6-462c-ad08-2359280bff34",
              }
            }
        }
    }

Mark a payment method as the active payment method

The last created payment method will always automatically be marked as active. You can switch between the payment methods by calling the /payment-method/<uuid>/set-active endpoint. This will mark all other payment methods of the related customer to "active": false.

HTTP Request

POST https://platform.tier-services.io/v1/payment-method/<uuid>/set-active

Error Cases

In case of an ongoing rental existing for the user, the service will return an HTTP 409 response.

The erro response will contain an errors array with a single entry with the code “SetActivePaymentMethodFailedOngoingRental”.

Query Parameters

No parameters

curl "https://platform.tier-services.io/v1/payment-method/5fa6987a-85f9-49fe-85cb-a639f58a43b6/set-active"
  -X POST
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
      "data": {
            "id": "5fa6987a-85f9-49fe-85cb-a639f58a43b6",
            "type": "payment-method",
            "attributes": {
                "provider": "LOGPAY",
                "name": "A name that is visible to the user",
                "active": true,
                "brand": "Enum value for CC brand or 'Unknown'"
            },
            "relationships": {
              "customer": {
                "type": "customer",
                "id": "092bd178-25a6-462c-ad08-2359280bff34",
              }
            }
        }
    }

Removing a Payment Method

HTTP Request

DELETE https://platform.tier-services.io/v1/payment-method/<uuid>

Deletion of payment methods results in a soft-delete, meaning the associated data remains in our database but will not be used for payments or shown to the user.

Error responses have return with HTTP - 409 and have the following structure:

Where code can contain any of the following strings: PaymentDeletionFailedIsActive, PaymentDeletionFailedOngoingRental, PaymentDeletionFailedUnpaidInvoices, PaymentDeletionFailedThirdParty, PaymentDeletionFailedInternal.

curl "https://platform.tier-services.io/v1/payment-method/5fa6987a-85f9-49fe-85cb-a639f58a43b6"
  -X DELETE
  -H "x-api-key: TIER API KEY"
  • The above command returns an empty response (204). Click ▶ button
Click to expand JSON data response 
    {
        "errors": [
            {
                "code": "PaymentMethodNotFound",
                "detail": "error detail",
                "title": "error title",
                "status": "404"
            }
        ]
    }

List payment method

ℹ Note that the format of the payload changes for each individual payment provider and that the payload is not returned again after having created the payment method.

HTTP Request

GET https://platform.tier-services.io/v1/payment-method

Query Parameters

Parameter Description
filter[customerId] Filter payment methods by customer id

Example: https://platform.tier-services.io/v1/payment-method?filter[customerId]=<customerId>

curl "https://platform.tier-services.io/v1/payment-method"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
      "data": [
            {
                "id": "5fa6987a-85f9-49fe-85cb-a639f58a43b6",
                "type": "payment-method",
                "attributes": {
                    "provider": "LOGPAY",
                    "name": "A name that is visible to the user",
                    "active": true,
                    "brand": "Enum value for CC brand or 'Unknown'"
                },
                "relationships": {
                    "customer": {
                        "type": "customer",
                        "id": "092bd178-25a6-462c-ad08-2359280bff34",
                    }
                }
            }
        ]
    }

Payment method-Specific error codes

The Tier API can respond with the following payment method specific error codes when creating the payment method of a customer:

Copy of Error Codes

Error Code Meaning Code
404 Customer not found CustomerNotFound
400 Payment method token is invalid InvalidPaymentMethod

When receiving an invalid paypalNonce

curl "https://platform.tier-services.io/v1/payment-method"
  -X POST
  -H "x-api-key: TIER API KEY"
  -d '{
    "provider": "BRAINTREE",
    "customer": {
      "id": "<uuid>"
    },
    "payload": { 
            "paypalNonce": <invalid_nonce> 
        },
  }'
  • returns a JSON structured like this if the paypalNonce is invalid. Click ▶ button
Click to expand JSON data response 
    {
        "errors": [
            {
                "code": "InvalidPaymentMethod",
                "title": "Invalid payment method",
                "status": "400"
            }
        ]
    }

When receiving a paypalNonce

curl "https://platform.tier-services.io/v1/payment-method"
  -X POST
  -H "x-api-key: TIER API KEY"
  -d '{
    "provider": "BRAINTREE",
    "customer": {
      "id": "<invalid_id>"
    },
    "payload": { 
            "paypalNonce": <paypalNonce> 
        },
  }'
  • and the customer does not exist, the API returns a JSON structured like this
Click to expand JSON data response 
    {
        "errors": [
            {
                "code": "CustomerNotFound",
                "title": "Customer not found",
                "status": "404"
            }
        ]
    }