Wallet addresses

Each payment account belonging to your users (e.g., customers) must have at least one associated wallet address for the account to be able to send and receive payments over Interledger and Open Payments. A wallet address serves as a publicly shareable standardized ID for a payment account.

Wallet address requirements

• Your Rafiki instance must be set up for at least one asset before wallet addresses can be created as each wallet address must have an asset assigned to it.
• Wallet address URLs are treated as case-insensitive, meaning that both lowercase and uppercase variations of the same address will be recognized as identical.

Create wallet addresses

There are a few ways in which you can create wallet addresses.

• Through a script
• In response to the wallet_address.not_found webhook event
• In the Rafiki Admin app

Create wallet addresses through a script

Writing your own script that loops through your list of account is one way to batch create wallet addresses for your existing account holders.

Ensure your script calls the createWalletAddress GraphQL mutation.

createWalletAddress mutation

mutation CreateWalletAddress($input: CreateWalletAddressInput!) {
  createWalletAddress(input: $input) {
    code
    success
    message
    walletAddress {
      id
      createdAt
      publicName
      url
      asset {
        code
        id
        scale
      }
    }
  }
}

We strongly recommend you store at least the walletAddress.id in your internal database to be able to reference the account and wallet address later.

Example

Example JSON request

{
  "input": {
    "assetId": "0ddc0b7d-1822-4213-948e-915dda58850b",
    "publicName": "Sarah Marshall",
    "url": "https://example.wallet.com/sarah",
    "additionalProperties": [
      {
        "key": "iban",
        "value": "NL93 8601 1117 947",
        "visibleInOpenPayments": false
      },
      {
        "key": "nickname",
        "value": "S Mar",
        "visibleInOpenPayments": true
      }
    ]
  }
}

Variable	Description
assetId	The unique ID of the asset, assigned by Rafiki when the asset was created, that the wallet address’s underlying payment account is denominated in
publicName	The public name associated with the wallet address
url	The wallet address’s case-insensitive URL
additionalProperties	Optional additional properties associated with the wallet address

Example JSON response

{
  "data": {
    "createWalletAddress": {
      "code": "200",
      "success": true,
      "message": "Created wallet address",
      "walletAddress": {
        "id": "695e7546-1803-4b45-96b6-6a53f4082018",
        "createdAt": "2023-03-03T09:07:01.107Z",
        "publicName": "Sarah Marshall",
        "url": "https://example.wallet.com/sarah",
        "asset": {
          "id": "0ddc0b7d-1822-4213-948e-915dda58850b",
          "code": "USD",
          "scale": 2
        }
      }
    }
  }
}

Create wallet addresses in response to a webhook event

The wallet_address.not_found event fires when a wallet address is requested through the Open Payments Get Wallet Address API, but Rafiki can’t find the address.

When you receive the event, look up the associated account in your system, then call the createWalletAddress mutation to create a wallet address for the account.

The mutation and example JSON request/response is the same as what’s given above.

Create and manage wallet addresses using Rafiki Admin

You can create and manage wallet addresses manually through the Rafiki Admin app.

Create a wallet address key pair

Creating a public-private key pair for each wallet address is not required when integrating with Rafiki.

You only need to create key pairs for wallet addresses if you want to allow your account holders to use/be Open Payments clients under their wallet addresses. For more information, review the Open Payments documentation about clients and client keys.

Use the createWalletAddressKey GraphQL mutation to create a key pair and associate it with a wallet address.

createWalletAddressKey mutation

mutation CreateWalletAddressKey($input: CreateWalletAddressKeyInput!) {
  createWalletAddressKey(input: $input) {
    code
    message
    success
    walletAddressKey {
      id
      walletAddressId
      revoked
      jwk {
        alg
        crv
        kid
        kty
        x
      }
      createdAt
    }
  }
}

Example

Example JSON request

{
  "input": {
    "jwk": {
      "kid": "keyid-97a3a431-8ee1-48fc-ac85-70e2f5eba8e5",
      "x": "ubqoInifJ5sssIPPnQR1gVPfmoZnJtPhTkyMXNoJF_8",
      "alg": "EdDSA",
      "kty": "OKP",
      "crv": "Ed25519"
    },
    "walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018"
  }
}

The request is a standard request to create a JSON Web Key (JWK), which is a JSON data structure that represents a cryptographic key. Section 4 of the JWK specification describes the format and associated parameters kty, alg, and kid. Section 6 of the JSON Web Algorithms (JWA) specification describes the cryptographic algorithm for the keys and associated parameters kty, crv, and x.

Open Payments requires the following values.

Parameter	Required value	Description
alg	EdDSA	The algorithm used to generate the key pair
kty	OKP	The key type identifying the cryptographic algorithm family used with the key
crv	Ed25519	The cryptographic curve used with the key

Additionally, the request must contain the walletAddressId of the wallet address that the key pair will be associated with.

Example JSON response

{
  "data": {
    "createWalletAddressKey": {
      "code": "200",
      "message": "Added Key To Wallet Address",
      "success": true,
      "walletAddressKey": {
        "id": "f2953571-f10c-44eb-ab41-4450a7ad6771",
        "walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018",
        "revoked": false,
        "jwk": {
          "alg": "EdDSA",
          "crv": "Ed25519",
          "kid": "keyid-97a3a431-8ee1-48fc-ac85-70e2f5eba8e5",
          "kty": "OKP",
          "x": "ubqoInifJ5sssIPPnQR1gVPfmoZnJtPhTkyMXNoJF_8"
        },
        "createdAt": "2023-03-03T09:26:41.424Z"
      }
    }
  }
}

Revoke a wallet address key

Use the revokeWalletAddressKey GraphQL mutation to revoke a public key associated with a wallet address. Open Payments requests using this key for request signatures will be denied going forward.

revokeWalletAddressKey mutation

mutation RevokeWalletAddressKey($input: RevokeWalletAddressKeyInput!) {
  revokeWalletAddressKey(input: $input) {
    walletAddressKey {
      id
      revoked
      walletAddressId
      createdAt
    }
  }
}

Example

Example JSON request

{
  "input": {
    "id": "e7532552-cff9-4ffe-883e-56613d3ae611"
  }
}

Example JSON response

{
  "data": {
    "revokeWalletAddressKey": {
      "walletAddressKey": {
        "id": "f2953571-f10c-44eb-ab41-4450a7ad6771",
        "revoked": true,
        "walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018",
        "createdAt": "2023-03-03T09:26:41.424Z"
      }
    }
  }
}