Direct Debit Customer Token

Tokenizing direct debit

Create an ACH direct debit customer token

Here is an example of a successful request for an ACH direct debit bank account tokenization to accept USD payment in US.

Create customer token using direct debit

POST https://staging.api.xpay.xcover.com/customer-tokens/direct-debit

Headers

Name	Type	Description
Authorization*	String	Bearer {{JWT}}

201: Created Direct debit successfully tokenized

422: Unprocessable Entity Problem tokenizing direct debit

Request

{
    "customer": {
      "email": "[email protected]"
    },
    "directDebit": {
        "type": "ACH Direct Debit",
        "bank": {
            "bankAccountNumber": "987654321",
            "bankLocationId": "011000138",
            "ownerName": "John Doe"
        },
        "billingAddress": {
            "city": "Sydney",
            "country": "US",
            "houseNumberOrName": "45",
            "postalCode": "2000",
            "stateOrProvince": "AL",
            "street": "Clarance St"
        }
    }
}

Response

HTTP 201

{
    "data": {
        "id": "5b20b67d-6be7-4f2f-ab1e-c5d2b993ac6a",
        "customerId": "091de65f-74c7-437e-b5a3-8acda7810153",
        "paymentProviderId": "35ea6da4-6500-43e9-bc44-b3848d3f3f9f",
        "createdAt": "2022-02-10T01:58:49+00:00",
        "updatedAt": "2022-02-10T01:58:49+00:00",
        "metadata": {
            "variant": "ach",
            "paymentMethod": "ACH Direct Debit",
            "number": "4321"
        },
        "partnerId": null,
        "isVisible": true,
        "isDefault": true,
        "isMultiToken": false,
        "createdBy": "76b52d93-12bf-31d1-b8fd-b9a6d125e43e"
    }
}

Failure Scenarios

There are many reasons why a tokenization of direct debit may fail. Here are some examples.

Missing bank account details

Request

{
    "customer": {
      "email": "[email protected]"
    },
    "directDebit": {
        "type": "ACH Direct Debit",
        "bank": {}
    }
}

Response

HTTP 422

{
    "message": "The given data was invalid.",
    "errors":  {
        "directDebit.bank": [
            "The direct debit.bank field is required."
        ],
        "directDebit.bank.bankAccountNumber": [
            "The direct debit.bank.bank account number field is required."
        ],
        "directDebit.bank.bankLocationId": [
            "The direct debit.bank.bank location id field is required."
        ],
        "directDebit.bank.ownerName": [
            "The direct debit.bank.owner name field is required."
        ]
    }
}

Invalid bank location ID

Request

{
    "customer": {
      "email": "[email protected]"
    },
    "directDebit": {
        "type": "ACH Direct Debit",
        "bank": {
            "bankAccountNumber": "987654321",
            "bankLocationId": "{{ Invalid bank location id }}",
            "ownerName": "John Doe"
        },
        "billingAddress": {`
            "city": "Sydney",
            "country": "US",
            "houseNumberOrName": "45",
            "postalCode": "2000",
            "stateOrProvince": "AL",
            "street": "Clarance St"
        }
    }
}

Response

HTTP 422

{
    "message": "Bank Account or Bank Location Id not valid or missing",
    "errors": {
        "paymentMethod": [
            "type: errorCode, code: 422, originalMessage: Bank Account or Bank Location Id not valid or missing"
        ]
    }
}