client/v1/transfer

[POST] client/v1/transfer

Post a payment with ACH_TRANSFER type

Allows Client Admin to create a payment with type ACH_TRANSFER to transfer funds from a customer account to client MSB account. This is to help facilitate a customer remittance payment flow. The intended implementation is to be 'behind the scenes' - a customer would operate a function on the client application to send money overseas and the client application would use the transfer endpoint to create the payment needed to transfer funds from the customer's account to the client's MSB account.

The payment type will be ACH_TRANSFER. Any ACH_TRANSFER payment type will automatically have the string Transfer to [[client name]] appended to the memo field. This payment type will also show up on statements and be available for notifications from the Payment Status Webhook.

Example [POST] Request

{
  "customerAccount": {
          "achAccountNumber": "" 
      },
      "customerAuthorized" : {
        "authorizedBy" : "", 
        "authorizationTimestampGMT" : "" 
      },
      "amount": "",             
      "transferType": "",       
      "currency": "",           
      "memo": ""                
}

Example Response

{
      "transfer": {
        "transferType": "REMITTANCE", // example from the first column in the account array
        "mainstreetBankAccount": {
          "transferAccountNumber": "",     
          "achRoutingNumber": ""
        },
        "amount": xxx,
        "currency": "usd",
        "scheduledDate": "",
        "numberOfPayments": "",
        "paymentsInterval": "",
        "memo": "",
        "firstName" : "",
        "middleInitial" : "",
        "lastName" : "",
        "address" : "",
        "city" : "",
        "state" : "",
        "zipCode" : "",
        "country" : "",
        "authorizedBy" : "John Smith",   // Name
        "authorizationTimestampGMT" : "2024-01-16T23:12:12.333333Z" //Date and timestamp
      },
      "paymentId": "xxxx",    // UUID payment identifier
      "sender": "",           // sender account number
      "status": "",           // status of payment at end of transaction. See link below.
      "dateCreated": "",      // Transaction processed date in format ISO 8601 YYYY-MM-DD. See link below
      "dateUpdated": "",      // Date of last status update in format ISO 8601 YYYY-MM-DD
      "publicTraceNumber": "xxxxxxxx"
    }

Input Parameters

Element	Details
"achAccountNumber"	Customer account number, routing number is hard coded
"authorizedBy"	The name of the person who authorized the transfer
"authorizationTimestampGMT"	Date and timestamp in GMT
"amount"	The amount being transferred. Amount will be positive The payment amount in lowest currency denomination e.g. cents. Global default limit of 100000 (cents) or $1,000 (USD) per transaction unless configured differently for your organization.
"transferType"	The type of account that is being transferred to (OPERATING or REMITTANCE). Pulls data from Account Array in client profile for corresponding ACH account number
"currency"	The currency (USD)
"memo"	The memo included with the transaction

Response Elements

Element	Details
"transferType"	The type of account that is being transferred to (OPERATING or REMITTANCE)
"transferAccountNumber"	The Mainstreet Bank account number
"achRoutingNumber"	The Mainstreet Bank routing number
"amount"	The amount being transferred
"currency"	The currency (USD)
"scheduledDate"	The date the payment is scheduled to transfer
"numberOfPayments"	The number of payments
"paymentsInterval"	The interval for payments
"memo"	The memo included with the transaction
"firstName"	The first name of the customer
"middleInitial"	The middle initial of the customer
"lastName"	The last name of the customer
"address"	The address of the customer
"city"	The city of the customer
"state"	The state of the customer
"zipCode"	The ZIP of the customer
"country"	The country of the customer
"authorizedBy"	The name of the person who authorized the transfer
"authorizationTimestampGMT"	When the authorization was made
"paymentId"	The ID for the transaction
"sender"	The account number sending the transfer
"status"	Current transaction status
"dateCreated"	The date the transaction was created
"dateUpdated"	The date the transaction was last updated
"publicTraceNumber"	The public trace number for the transaction

Input Validation

Parameter	Format	Requirement
achAccountNumber	5-17 digits No special characters `(" !"#$%&'()\*+,-./:;\<\=>?@\[\]^\_\`{\|}~")`	Yes
authorizedBy	up to 105 characters No special characters `(" !"#$%&'()\*+,-./:;\<\=>?@\[\]^\_\`{\|}~")`	Yes
authorizationTimestampGMT	ISO 8601 yyyy-mm-ddThh:mm:ss.ssssssZ	Yes
amount	> 0 and < = 50000 [$500 dollars] No special characters `(" !"#$%&'()\*+,-./:;\<\=>?@\[\]^\_\`{\|}~")`	Yes
transferType	‘Remittance’ or ‘Operating’ No special characters (" !"#$%&'() * +,-./:; < =>?@ [ ] ^ _ ` { \| }~")	Yes
currency	‘USD’ `[ISO Alpha 3 standard]`	Yes
memo	< = 250 characters	Yes

Error Codes

Category	Response Code	Error Message
Format (F)	CA3015	Invalid Format
Size (S)	CA3015	Invalid Length
Required (R)	CA3000	Missing Required Field
Business (B1)	CA3016	amount cannot exceed `<transfer limit in cents>`

Error code responses

{
  "errorCodeMessageList": [
      {
          "code": "CA3000-1R", // 1 refers to first field, R refers to Required
          "message": "Missing Required Field"
      },
      {
          "code": "CA3105-2F", // 2 refers to the second field, F refers to Format
          "message": "Invalid Format"
      },
      {
          "code": "CA3105-7S", // 7 refers to the seventh field, S refers to Size
          "message": "Invalid Length"
      }
  ]
}