Skip to content

add internal account status #469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wuvictor-95 merged 1 commit into from
May 14, 2026
Merged

add internal account status #469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

45 changes: 45 additions & 0 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions openapi/components/schemas/customers/InternalAccount.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ type: object
required:
- id
- type
- status
- balance
- fundingPaymentInstructions
- createdAt
Expand All @@ -17,6 +18,8 @@ properties:
example: Customer:019542f5-b3e7-1d02-0000-000000000001
type:
$ref: ./InternalAccountType.yaml
status:
$ref: ./InternalAccountStatus.yaml
balance:
$ref: ../common/CurrencyAmount.yaml
fundingPaymentInstructions:
Expand Down
25 changes: 25 additions & 0 deletions openapi/components/schemas/customers/InternalAccountStatus.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
title: Internal Account Status
Copy link
Copy Markdown
Contributor

@shreyav shreyav May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we also send webhooks on status changes?

Copy link
Copy Markdown
Contributor Author

@wuvictor-95 wuvictor-95 May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added

type: string
enum:
- PENDING
- ACTIVE
- CLOSED
- FROZEN
description: >-
Status of a Grid internal account. The status determines whether the account
can send or receive payments.


- `PENDING`: The account is under review and is being provisioned. The account
cannot send or receive payments until provisioning completes.

- `ACTIVE`: The account is ready to send and receive payments.

Copy link
Copy Markdown
Contributor

@pengying pengying May 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a state diagram with markdown?

Can an account be closed with a non zero balance? Or is there a PENDING_CLOSED where debits can occur but no credits before the account is closed?

What triggers an account to go from PENDING > ACTIVE?

Copy link
Copy Markdown
Contributor Author

@wuvictor-95 wuvictor-95 May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had similar questions. Erebor said an account can be frozen or closed entirely for various compliance reasons. Frozen can be recovered, closed cannot. I would imagine the account could not receive or send money in these states but I can double check.

PENDING means the account is being provisioned and undergoing review by the banking partner. Once approved, it moves to OPEN

- `CLOSED`: The account cannot send or receive payments. A customer can
Copy link
Copy Markdown
Contributor

@pengying pengying May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

closed is terminal? No undo right?

Copy link
Copy Markdown
Contributor Author

@wuvictor-95 wuvictor-95 May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. Some new information here: https://docs.erebor.bank/accounts/deposit-accounts#account-lifecycle

I'm just seeing this since Erebor did not have guides before. But looks like we can follow the same logic of closing it down when balance is 0. I can add some more validation.

Copy link
Copy Markdown
Contributor

@pengying pengying May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cool. what's the password to the docs?

Copy link
Copy Markdown
Contributor

@jklein24 jklein24 May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wuvictor-95 please don't respond to that question here in this public repo :-)

initiate the closing of an internal account, after which the account
transitions to this status.

- `FROZEN`: The account cannot send or receive payments. Grid may freeze an
account in response to compliance or fraud signals; payments are blocked
while the account remains frozen.
example: ACTIVE
1 change: 1 addition & 0 deletions openapi/components/schemas/webhooks/InternalAccountStatusWebhook.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,4 @@ allOf:
type: string
enum:
- INTERNAL_ACCOUNT.BALANCE_UPDATED
- INTERNAL_ACCOUNT.STATUS_UPDATED
1 change: 1 addition & 0 deletions openapi/components/schemas/webhooks/WebhookType.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ enum:
- VERIFICATION.PENDING_MANUAL_REVIEW
- VERIFICATION.READY_FOR_VERIFICATION
- INTERNAL_ACCOUNT.BALANCE_UPDATED
- INTERNAL_ACCOUNT.STATUS_UPDATED
- INVITATION.CLAIMED
- BULK_UPLOAD.COMPLETED
- BULK_UPLOAD.FAILED
Expand Down
1 change: 1 addition & 0 deletions openapi/paths/internal_accounts/internal_accounts_{id}.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ patch:
id: InternalAccount:019542f5-b3e7-1d02-0000-000000000002
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
type: EMBEDDED_WALLET
status: ACTIVE
balance:
amount: 12550
currency:
Expand Down
26 changes: 26 additions & 0 deletions openapi/webhooks/internal-account-status.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@ post:
account changes. The `data` payload contains the full internal account
object.

- `INTERNAL_ACCOUNT.STATUS_UPDATED` — Fired when the status of an internal
account changes (e.g., `OPEN` → `FROZEN`). The `data` payload contains the
full internal account object.


operationId: internalAccountStatusWebhook
tags:
Expand All @@ -57,6 +61,28 @@ post:
id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
type: INTERNAL_FIAT
status: ACTIVE
balance:
amount: 10000
currency:
code: USD
name: United States Dollar
symbol: $
decimals: 2
fundingPaymentInstructions: []
createdAt: '2025-08-01T10:00:00Z'
updatedAt: '2025-08-15T14:32:00Z'
statusUpdated:
summary: The status of an internal account changed (e.g., frozen by Grid)
value:
id: Webhook:019542f5-b3e7-1d02-0000-000000000008
type: INTERNAL_ACCOUNT.STATUS_UPDATED
timestamp: '2025-08-15T14:32:00Z'
data:
id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005
customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
type: INTERNAL_FIAT
status: FROZEN
balance:
amount: 10000
currency:
Expand Down
Loading