Migrating to Smart Transfers API

Let Trice route your payment instruction to the correct rail (RTP or FedNow) based on what rails the account supports, the bank's status (signed on or off), and the preferences that you indicate.

If you're creating transfers using the rtp_transfers or fednow_transfers endpoints, this guide will help you migrate to the new Smart Transfer API.

1. Discontinue using deprecated fields

1. Account request and response fields
   1. capabilities
      1. party_underwriter and underwriter-> moved to Bank Capabilities API
      2. intermediary_rtp_v_2_9, intermediary_rtp_v_3_0, rfp_rtp_v_2_9, rfp_rtp_v_3_0, rtp_rfps, rtp_transfers, and transaction_monitor_parent -> moved to Enrollments API
   2. enrollments -> moved to Enrollments API
   3. verified-> use verified_for field
2. Person request and response fields
   1. verified-> use verified_for field
3. Party request and response fields
   1. verified-> use verified_for field

2. Add fednow.sender scope to your access token

curl --request POST \
     --url https://api-sandbox.trice.co/auth/v1/oauth2/token \
     --header 'accept: application/json' \
     --header 'authorization: Basic <base64(username:password)>' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data 'scope=fednow.sender rtp.sender'

3. Check your enrollment's capabilities

Check that your enrollment has the following capabilities active: rtp_transfers and fednow_transfers

curl --request GET \
     --url https://api-sandbox.trice.co/hub/v1/enrollments \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your-token>'

# Response
{
  "data": [
    {
     ...
      "capabilities": {
        "fednow_transfers": "active",
        "rtp_transfers": "active",
        ...
      },
      ...
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/enrollments"
}

4. Get ready for FedNow webhook events (if using webhooks)

We added 2 new types of webhook configurations:

1. fednow_transfer_outbound
2. fednow_transfer_inbound

If you have a webhook configuration with type=default, you will start receiving FedNow webhook events without any further changes.

5. Update your integration to use Smart Transfer API

1. Change endpoint to smart_transfer from either rtp_transfer or fednow_transfer.
2. The request payload is the same, with some new fields to indicate your rail preferences.
3. The response contains report object and either rtp_transfer or fednow_transfer object based on which rail was used

curl --request POST \
     --url https://api-sandbox.trice.co/hub/v1/smart_transfer \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your-token>' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 10000,
  "enrollment": "669774a5-dbbc-481f-99ab-8c7c99d57777",
  "internal_description": "Can use this for reconciliation or support",
  "memo": "This is sent to the receiving bank",
  "reference_number": "bill5439trice"
}
'

# Response
{
  "report": [
    {
      "network": "rtp",
      "reason": "transfer sent to network successfully",
      "status": "success"
    },
    {
      "network": "fednow",
      "reason": "not needed, transfer already successfully sent to network",
      "status": "omitted"
    }
  ],
  "rtp_transfer": {
    "amount": 1,
    "completed": null,
    "created": "2024-10-23 17:45:20.434032",
    "enrollment": {
      ...
    },
    "fee": 0,
    "id": "929d02ee-9166-11ef-b6d6-f146864c5276",
    "internal_description": "Transfer for bills that need paid.",
    "memo": "TRICE ACCOUNT REAL TIME PAYMENT TRANSFER",
    "party": {
      ...
    },
    "reference_number": "bill5439trice",
    "returned": null,
    "rtp_rfp_id": null,
    "sender": null,
    "state_details": null,
    "status": "created",
    "type": "outbound",
    "ultimate_receiving_party": null,
    "ultimate_sending_party": null
  }
}

See Create an RTP or FedNow transfer docs

6. Test your integration in sandbox (available now!)

7. Start using the new APIs in production (available now!)