Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Use cases API Changelog
  1. Guides
  2. Money movement
  3. Accept payments
  4. Card acceptance

Statement descriptors

Learn how to customize statement descriptors on card payments.

Statement descriptors are the text that describe transactions presented to us by our digital banking feeds (or paper statements) so that we can recognize them. Setting clear statement descriptors can help to reduce disputes and improve the user experience by providing context on what the payment was for.

For card payments, Moov will use the statement descriptor added at the transfer or account level. Otherwise, Moov will default to the DBA or legal business name of the Moov account truncated based on payment network limits.

Account level statement descriptor

You can set the default statement descriptor for a merchant by using the account.settings.cardPayment.statementDescriptor field in the PATCH accounts endpoint. In the example provided, we set a statement descriptor for a local gym called “Whole Body Fitness” at the account level.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

curl -X PATCH "https://api.moov.io/accounts/{accountID}" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "accountType": "business",
    "profile": {
      "business": {
        "legalBusinessName": "Whole Body Fitness LLC",
        "businessType": "llc"
      }
    },  
    "settings": {
      "cardPayment": {
        "statementDescriptor": "Whole Body Fitness"
      }
    }
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

mc, _ := moov.NewClient()

updatedAccount := moov.Account{
  AccountID:   "UUID",
  AccountType: moov.AccountType_Business,
  Profile: moov.Profile{
    Business: &moov.Business{
      LegalBusinessName: "Whole Body Fitness LLC",
      BusinessType: moov.BusinessType_Llc,
    },
  },
  Settings: &moov.AccountSettings{
    CardPayment: &moov.CardPaymentSettings{
        StatementDescriptor: "Whole Body Fitness",
    },
  },
}

mc.UpdateAccount(ctx, updatedAccount)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const moov = new Moov(credentialsObject);

const updatedAccount = {
  settings: {
    cardPayment: {
      statementDescriptor: "Whole Body Fitness"
    }
  }
};


const account = await moov.accounts.patch(updatedAccount);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const moov = Moov(token);

const updatedAccount = {
  accountType: "business",
  profile: {
    business: {
      legalBusinessName: "ClassBooker",
      businessType: "llc"
    }
  },
  settings: {
    cardPayment: {
      statementDescriptor: "Whole Body Fitness",
    }
  }
};

moov.accounts.update(updatedAccount);

American Express statement descriptors

Before a transaction settles with the bank, American Express statements may show a description of Moov Financial instead of the statementDescriptor that has been set for the merchant. Once the transaction settles and moves beyond the pending stage, the description will update with the statement descriptor that has been set for the merchant.

To avoid any confusion about the origin of the transaction, this information should be passed along to merchants to share with customers.

Transfer level statement descriptor

Business accounts must be approved by Moov to set the source.cardDetails.dynamicDescriptor when creating a transfer. This field is an optional override of the default card statement descriptor, which allows a merchant to pass information to the card issuer at the time of transaction. The card issuer will then use this information to generate a description of the cardholder’s statement. In the example provided, we set a dynamic statement descriptor that captures the date of a yoga class at Whole Body Fitness.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

curl -X POST "https://api.moov.io/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "amount": {
      "value": 100,
      "currency": "USD"
    },
    "destination": {
      "paymentMethodID": "UUID"
    },
    "source": {
      "paymentMethodID": "UUID",
      "cardDetails": {
        "dynamicDescriptor": "WhlBdy *Yoga 11-12"
      }
    },
    "description": "Paying Jules for last 4 classes"
  }'\

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

mc, _ := moov.NewClient()

mc.CreateTransfer(ctx, moov.CreateTransfer{
  Amount: moov.Amount{
    Currency: "usd",
    Value:    100, // $1.00
  },
  Destination: moov.CreateTransfer_Destination{
    PaymentMethodID: "UUID",
  },
  Source: moov.CreateTransfer_Source{
    PaymentMethodID: "UUID",
    CardDetails: &moov.CreateTransfer_CardDetailsSource{
      DynamicDescriptor: "WhlBdy *Yoga 11-12",
    },
  },
  Description: "Paying Jules for last 4 classes",
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

const moov = new Moov(credentialsObject);

const transferPayload =  {
  amount: {
    value: 100,
    currency: "USD"
  },
  destination: {
    paymentMethodID: "UUID"
  },
  source: {
    paymentMethodID: "UUID",
    cardDetails: {
      dynamicDescriptor: "WhlBdy *Yoga 11-12"
    }
  },
  description: "Paying Jules for last 4 classes"
}

const transfer = await moov.transfers.create(transferPayload);
Summary Beta