Introduction

The following is accurate as of November 2021 and forward, reviewing key features and details of our API compatible back end payments hub to aid consumption of our services.


Transaction Codes

Transaction codes are an integral part of identifying and classifying payment records via API. Refer to Account History and Transaction Codes documentation section for more deatils.


unique_id vs. payment_id

Some important details about these similar reference fields are:

  • "unique_id" will not go away for the foreseeable future. It is critical for the account/history endpoint as a way (intraday) to recognize new transactions when polling data throughout the day.
  • "payment_id" is the method to reference and join new payments and account/history, and is parsed in the GET account/history response.

POST payment

Use this endpoint for initiating wire payments via API. To initiate a payment the customer API Subscription must have wire API transfer approval with the following requirements:

  1. Services requested by customer and approved by Silvergate Service team
  2. Updated cash management agreements signed and returned by customer
  3. Configured by Silvergate
    • Configuration for POST payment is at the Subscription level (as opposed to per account). Customers may request and setup separate Subscriptions to use in conjunction with POST and/or PUT payment operations

PATCH payment

This operation allows the user to Approve, Cancel, or Return a payment. Note that there is no separate entry from approval requirements built into the flow.

See online documentation for URL, Request and Response specification details.

Approval

Approvals are required for every payment submitted via API. Approvals are only accepted once after initiation via API POST when the Status = “Pre-approval”.

Using the PATCH operation enter Action = “approve” with the timestamp returned in the POST payment or GET payment response message.

Cancellation

This feature allows for explicit cancelation, which will move a payment into “Pending Cancellation” status. Payments initiated but never approved will be automatically canceled after 1 business day.

Using the PATCH operation enter Action = "cancel" with the timestamp returned in the POST payment or GET payment response message.

Returns

Explicit returns are an effective method to send back unwanted funds for any business reason, to prevent the payments from coming back again and turning into a repetitive process. From a Fedwire perspective we will be turning these payments into a type 1002 (same day return) or 1008 (return comes 1 or more days after receipt of funds).

Return Steps

  1. Using the PATCH operation, enter action = “return” with the “payment_id” of the original incoming payment to be returned along with the timestamp returned in the GET payment response message. Successful requests create a new payment, which effectively reverses the payment instructions of the original. Response gives the new “payment_id” of the return.
  2. Use the PATCH operation again, this time with action = “approve” along with new “payment_id” and “payment_timestamp”.
  3. Track the relationship between the two payments using GET payment and specifically see the original “payment_id” in the “reference_for_beneficiary” field on the new outgoing return payment.

Backup for API Wire Initiation

If for any reason a customer cannot use the API operations, one alternative method is to use Silvergate’s online banking ad hoc or batch upload wire submission protocols.

Additionally, notifications will be sent in the event alternative POST payment endpoints are required during business continuity planning periods.


Cutoff Times

(Note: All times referenced below are in Pacific Time—following daylight savings standards—on Federal Banking days. See here for Federal holidays observed.)

As of April 4, 2021, same day released payments must be initiated by 3:00 PM. If initiated after 3:00 PM processing will occur on the following business day. If initiated before 3:00 PM, the absolute approval cutoff is 3:30 PM, although payments approved after 3:00 PM are less likely to be processed same day. For time zone clarity, this means UTC-8 during daylight savings from early November to mid-March and UTC-7 the remainder of the year.


Daily Limit

The customer must choose a maximum daily cumulative dollar limit for wire payments submitted via API. This is based on payment date, therefore utilizes banking days only. Submissions over the weekend and on holidays are rolled up to the next banking day. The reset time is 3:00 PM Pacific on banking days because this is the cutoff time when we automatically start scheduling new requests for the following banking day.


Idempotency-key

Customers can utilize duplicate payment control by sending an optional idempotency key in the header. The scenarios around idempotent POST payment requests are as follows:

  1. Not Passed – It is optional, therefore if idempotency key not passed, code will run as normal to attempt POST payment. No checks to the idempotency database (db) will occur.

  2. Key passed for first time use

    • If check for key in db returns no records, key will get added to the db; record will initially have a status of New (“1”)

    • Initiate payment is called

      • If success returned, record updated with status of Success (“2”), and results from core system stored in db record and returned to customer

      • If failure or exception returned, results are updated with a status of Fail (“3”), record is updated in db and error message returned in response to customer

  3. Key passed, already exists in db

    • Check for key in db, key is found

    • If status of found record = “2”, result data is deserialized to the Response object and returned to the user (as 200 OK). New payment is not initiated. Note that only the key is evaluated.

    • If status of found record = "3", resulting Error returned to the user (400 bad request or 500 server error) with the value stored in the result of the record

    • If status of found record = "1" or anything else, error is returned to the user (bad request) with message indicating that the key is currently being processed, prompting to please try again later to get the result. There is a slight potential for a record to get stuck in this state if a new record gets written to the db and the api service goes down before writing the response from wire system. If this scenario is suspected customer can contact Silvergate API support.

In summary, once a record for an idempotency key has been written to the db, that result will always be returned from a post call with the matching id and the code will never call the payment service again as long as that key exists in the db. Database records will be deleted 30 days after initial insert.


Outgoing Payment "Bank Chain" Flows

Payments originating at Silvergate will always return customer's Silvergate relationship/account as the Sending Bank (Fed tag 3100). Terminal recipient of funds will always return as beneficiary_bank (Fed tag 3100).

For two-bank scenarios, beneficiary_bank is ABA only. (Note: If POST payment submitted with 'Receiving Bank' ID but no beneficiary_bank details, 'Receiving Bank' will be treated as beneficiary_bank.)

For three-bank scenarios, a Receiving Bank (Fed 3400, ABA) will come before the beneficiary_bank, for which bank type may be ABA or SWIFT or Acct.

For four-bank scenarios, a Receiving Bank (Fed 3400, ABA) and Intermediary Bank (Fed 4000, ABA or SWIFT or Acct) will come before the beneficiary_bank, for which bank type may be SWIFT or Acct.


Inbound Payment "Bank Chain" Flows

Complete inbound payments will always classify the customer's Silvergate relationship/account as the Receiving Bank (Fed tag 3400), and details will return in beneficiary_bank fields. The counterparty where the payment initiated may be classified as the Sending Bank (Fed 3100) in a two-bank domestic payment scenario or the Originating Bank (Fed 5100) in all other scenarios.

For three-bank scenarios, the Originating Bank (Fed 5100) will be followed by a Sending Bank (3100).

For four-bank scenarios, the Originating Bank (Fed 5100) will be followed by an Instructing Bank (Fed 5200) or Intermediary Bank (Fed 4000) before a Sending Bank (3100).

For five-bank scenarios, the Originating Bank (Fed 5100) will be followed by an Instructing Bank (Fed 5200), then an Intermediary Bank (Fed 4000), then a Sending Bank (3100), before reaching Silvergate (the Receiving Bank, Fed 3400)


Inbound Payments to Virtual Accounts

For certain client types, Silvergate offers a virtual account product, which will impact how inbound payments appear. Please contact your Silvergate account manager for details.