{"_id":"57e95dd45c01360e00a2c190","parentDoc":null,"project":"54e405191e51932d006abc39","version":{"_id":"55fa37c88065a10d004e5bb6","project":"54e405191e51932d006abc39","__v":9,"createdAt":"2015-09-17T03:47:20.956Z","releaseDate":"2015-09-17T03:47:20.956Z","categories":["55fa37ca8065a10d004e5bb7","55fa37ca8065a10d004e5bb8","55fa37ca8065a10d004e5bb9","55fa37ca8065a10d004e5bba","55fca6bf34ae7c0d00ab8ea0","55ff80fd9e7ccf0d000a1d93","560220af7435de0d00fabd0d","56107f21bb9d920d00303e70","563e184077681a0d00d96a02","56fafc6596ec7e0e002ac85f","5915e54f7c2c552d008b8549","59499fcd64b5f5002690bbc1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"REST V3","version_clean":"3.1.0","version":"3.1"},"user":"54e4044e8ef7552300409dcb","__v":1,"category":{"_id":"59499fcd64b5f5002690bbc1","project":"54e405191e51932d006abc39","version":"55fa37c88065a10d004e5bb6","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-06-20T22:21:01.625Z","from_sync":false,"order":2,"slug":"quickstart-flows","title":"Quickstart Flows"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-26T17:41:40.253Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Onboarding users (KYC) and payment flows are customized for every platform. We recommend [contacting us](doc:contact-us) before you start developing against our APIs. But if you are curious and still want to test out our APIs, this common flow can help.\n\nThe payout flow is ideal for applications that want to send money to their users. This flow will show you how to create users, add KYC, open subaccounts and make transfers.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/36b5715-Untitled_Diagram_11.png\",\n        \"Untitled Diagram (11).png\",\n        341,\n        61,\n        \"#191919\"\n      ],\n      \"border\": false,\n      \"sizing\": \"smart\",\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\n## 1. CREATE USER ACCOUNT AND ADD KYC\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST https://uat-api.synapsefi.com/v3.1/users -H 'content-type: application/json' -H 'x-sp-gateway: client_id_5p7x3zfEglJOGcR2beTCyNAKtLnVSFBXh6vdos4k|client_secret_nP213c0wuyWIdKZRXmjHTDC0FxNBkvLoVYfi6glt' -H 'x-sp-user: |e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' \\n  -d '{\\n  \\\"logins\\\": [\\n    {\\n      \\\"email\\\": \\\"test:::at:::synapsepay.com\\\"\\n    }\\n  ],\\n  \\\"phone_numbers\\\": [\\n    \\\"901.111.1111\\\",\\n    \\\"test@synapsepay.com\\\"\\n  ],\\n  \\\"legal_names\\\": [\\n    \\\"Test User\\\"\\n  ],\\n  \\\"documents\\\":[{\\n        \\\"email\\\":\\\"test@synapsepay.com\\\",\\n        \\\"phone_number\\\":\\\"901.111.1111\\\",\\n        \\\"ip\\\":\\\"::1\\\",\\n        \\\"name\\\":\\\"Test User\\\",\\n        \\\"alias\\\":\\\"Test\\\",\\n        \\\"entity_type\\\":\\\"M\\\",\\n        \\\"entity_scope\\\":\\\"Arts & Entertainment\\\",\\n        \\\"day\\\":2,\\n        \\\"month\\\":5,\\n        \\\"year\\\":1989,\\n        \\\"address_street\\\":\\\"1 Market St\\\",\\n        \\\"address_city\\\":\\\"SF\\\",\\n        \\\"address_subdivision\\\":\\\"CA\\\",\\n        \\\"address_postal_code\\\":\\\"94114\\\",\\n        \\\"address_country_code\\\":\\\"US\\\"\\n    }],\\n  \\\"extra\\\": {\\n    \\\"supp_id\\\": \\\"122eddfgbeafrfvbbb\\\",\\n    \\\"cip_tag\\\":1,\\n    \\\"is_business\\\": false\\n  }\\n}'\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"{\\n    \\\"_id\\\": \\\"59499bc6838454002fd0c096\\\",\\n    \\\"_links\\\": {\\n        \\\"self\\\": {\\n            \\\"href\\\": \\\"https://uat-api.synapsefi.com/v3.1/users/59499bc6838454002fd0c096\\\"\\n        }\\n    },\\n    \\\"client\\\": {\\n        \\\"id\\\": \\\"5949989f23dbf000229bdbaf\\\",\\n        \\\"name\\\": \\\"Test Platform\\\"\\n    },\\n    \\\"doc_status\\\": {\\n        \\\"physical_doc\\\": \\\"MISSING|INVALID\\\",\\n        \\\"virtual_doc\\\": \\\"MISSING|INVALID\\\"\\n    },\\n    \\\"documents\\\": [\\n        {\\n            \\\"id\\\": \\\"dcd19da5fb2470984d0e316fb5551269e65c109730b0b45b32a8bb1eb83d6a72\\\",\\n            \\\"name\\\": \\\"Test User\\\",\\n            \\\"permission_scope\\\": \\\"UNVERIFIED\\\",\\n            \\\"physical_docs\\\": [],\\n            \\\"social_docs\\\": [\\n                {\\n                    \\\"document_type\\\": \\\"IP\\\",\\n                    \\\"id\\\": \\\"28d9177b22c127d9a51d8903893864accf6e553ac326704a4c0d585eaad2516a\\\",\\n                    \\\"last_updated\\\": 1497996229732,\\n                    \\\"status\\\": \\\"SUBMITTED|VALID\\\"\\n                },\\n                {\\n                    \\\"document_type\\\": \\\"PHONE_NUMBER\\\",\\n                    \\\"id\\\": \\\"fda60784d6375bc44edafaaeae149626c4c13dcb92e85a2a7a00eec2cdfd2b6f\\\",\\n                    \\\"last_updated\\\": 1497996229222,\\n                    \\\"status\\\": \\\"SUBMITTED|VALID\\\"\\n                },\\n                {\\n                    \\\"document_type\\\": \\\"EMAIL\\\",\\n                    \\\"id\\\": \\\"b886811ff9cbc150065c65eb5295951ac624e3a63e57d5e016cfddc03904f46b\\\",\\n                    \\\"last_updated\\\": 1497996228710,\\n                    \\\"status\\\": \\\"SUBMITTED|VALID\\\"\\n                }\\n            ],\\n            \\\"virtual_docs\\\": [\\n                {\\n                    \\\"document_type\\\": \\\"SSN\\\",\\n                    \\\"id\\\": \\\"ee596c2896dddc19b76c07a184fe7d3cf5a04b8e94b9108190cac7890739017f\\\",\\n                    \\\"last_updated\\\": 1497996228195,\\n                    \\\"status\\\": \\\"SUBMITTED|VALID\\\"\\n                }\\n            ]\\n        }\\n    ],\\n    \\\"emails\\\": [],\\n    \\\"extra\\\": {\\n        \\\"cip_tag\\\": 1,\\n        \\\"date_joined\\\": 1497996227163,\\n        \\\"extra_security\\\": false,\\n        \\\"is_business\\\": false,\\n        \\\"last_updated\\\": 1497996227163,\\n        \\\"public_note\\\": null,\\n        \\\"supp_id\\\": \\\"122eddfgbeafrfvbbb\\\"\\n    },\\n    \\\"is_hidden\\\": false,\\n    \\\"legal_names\\\": [\\n        \\\"Test User\\\"\\n    ],\\n    \\\"logins\\\": [\\n        {\\n            \\\"email\\\": \\\"test@synapsepay.com\\\",\\n            \\\"scope\\\": \\\"READ_AND_WRITE\\\"\\n        }\\n    ],\\n    \\\"permission\\\": \\\"UNVERIFIED\\\",\\n    \\\"phone_numbers\\\": [\\n        \\\"test@synapsepay.com\\\",\\n        \\\"901.111.1111\\\"\\n    ],\\n    \\\"photos\\\": [],\\n    \\\"refresh_token\\\": \\\"refresh_FBCt0DOU9NvcfKpe3lbr7ghisaoq2ImduPERx4nW\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nIn the response, you get back an `_id` associated with the user. You should store this `_id`. In addition, the `refresh_token` is included in the response which will be used to generate OAuth access, which allows you to perform operations on behalf of the user.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"User verification is async. If you do `GET` user after the `POST` user API call and all documents have been submitted and verified, the user will have `RECEIVE` permissions. For a user to be able to send funds to the platform, their account permissions need to be `RECEIVE`.\",\n  \"title\": \"Asynchronous User Verification\"\n}\n[/block]\n### OAuth User:\n\nIf you are using one of the Client libraries, this step is not required because the libraries automatically handle OAuth after the user is created.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -H \\\"Content-Type: application/json\\\" -H \\\"X-SP-GATEWAY: e3f19e4bd4022c86e7f2|11c94ba6bad74d24a0158bc707f0fc19a86dc08f\\\" -H \\\"X-SP-USER-IP: 107.170.246.225\\\" -H \\\"X-SP-USER: |e716990e50b67a1177736960b6357524b22090ccab093d068b3d7a18dbde3f4c\\\" -d '{\\n    \\\"refresh_token\\\": \\\"refresh-3a09773f-388e-472b-ad1e-fccba7c2f152\\\"\\n}' \\\"https://sandbox.synapsepay.com/api/3/oauth/57e468f086c2733736c13314\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"{\\n  \\\"expires_at\\\": \\\"1474594065\\\",\\n  \\\"expires_in\\\": \\\"7117\\\",\\n  \\\"oauth_key\\\": \\\"oauth-e8115f89-0153-4162-b024-36669ece4796\\\",\\n  \\\"refresh_expires_in\\\": 19,\\n  \\\"refresh_token\\\": \\\"refresh-3a09773f-388e-472b-ad1e-fccba7c2f152\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nFrom the response, you need to capture the `oauth_key` to make further requests on the user's behalf.\n\n\n##2. LINK EXTERNAL ACCOUNT\n\nIn this step we will allow the user to link an external bank account by using their account and routing number.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST https://uat-api.synapsefi.com/v3.1/users/59499bc6838454002fd0c096/nodes -H 'content-type: application/json' -H 'postman-token: 3c4de184-81d0-3172-3be0-64f94a290f66' -H 'x-sp-user: oauth_ixp3DgkQatY7jXy50KqMsBmUAWVFouLS02EwnGJd|e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' -d '{\\n  \\\"type\\\": \\\"ACH-US\\\",\\n  \\\"info\\\": {\\n    \\\"nickname\\\": \\\"Fake Account\\\",\\n    \\\"account_num\\\": \\\"1232225674134\\\",\\n    \\\"routing_num\\\": \\\"051000017\\\",\\n    \\\"type\\\": \\\"PERSONAL\\\",\\n    \\\"class\\\": \\\"CHECKING\\\"\\n  }\\n}'\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"{\\n    \\\"error_code\\\": \\\"0\\\",\\n    \\\"http_code\\\": \\\"200\\\",\\n    \\\"limit\\\": 20,\\n    \\\"node_count\\\": 1,\\n    \\\"nodes\\\": [\\n        {\\n            \\\"_id\\\": \\\"5949c6a14d1d6200373101f0\\\",\\n            \\\"_links\\\": {\\n                \\\"self\\\": {\\n                    \\\"href\\\": \\\"https://uat-api.synapsefi.com/v3.1/users/59499bc6838454002fd0c096/nodes/5949c6a14d1d6200373101f0\\\"\\n                }\\n            },\\n            \\\"allowed\\\": \\\"CREDIT\\\",\\n            \\\"client\\\": {\\n                \\\"id\\\": \\\"5949989f23dbf000229bdbaf\\\",\\n                \\\"name\\\": \\\"Test Platform\\\"\\n            },\\n            \\\"extra\\\": {\\n                \\\"other\\\": {},\\n                \\\"supp_id\\\": \\\"\\\"\\n            },\\n            \\\"info\\\": {\\n                \\\"account_num\\\": \\\"4134\\\",\\n                \\\"address\\\": \\\"8001 VILLA PARK DRIVE, HENRICO, VA, US\\\",\\n                \\\"balance\\\": {\\n                    \\\"amount\\\": \\\"0.00\\\",\\n                    \\\"currency\\\": \\\"USD\\\"\\n                },\\n                \\\"bank_long_name\\\": \\\"BANK OF AMERICA\\\",\\n                \\\"bank_name\\\": \\\"BANK OF AMERICA\\\",\\n                \\\"class\\\": \\\"CHECKING\\\",\\n                \\\"match_info\\\": {\\n                    \\\"email_match\\\": \\\"not_found\\\",\\n                    \\\"name_match\\\": \\\"not_found\\\",\\n                    \\\"phonenumber_match\\\": \\\"not_found\\\"\\n                },\\n                \\\"name_on_account\\\": \\\" \\\",\\n                \\\"nickname\\\": \\\"Fake Account\\\",\\n                \\\"routing_num\\\": \\\"0017\\\",\\n                \\\"type\\\": \\\"PERSONAL\\\"\\n            },\\n            \\\"is_active\\\": true,\\n            \\\"timeline\\\": [\\n                {\\n                    \\\"date\\\": 1498007200994,\\n                    \\\"note\\\": \\\"Node created.\\\"\\n                }\\n            ],\\n            \\\"type\\\": \\\"ACH-US\\\",\\n            \\\"user_id\\\": \\\"59499bc6838454002fd0c096\\\"\\n        }\\n    ],\\n    \\\"page_count\\\": 1,\\n    \\\"success\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nSince the user is only receiving funds, micro-deposit verification is not required since the user's node has `CREDIT` permissions already.\n\nFrom the response, you need to capture the `_id`. Now the user's external account is ready to receive funds. Both your user and your platform nodes are created. The next step is for you to create a transaction going your Platform's deposit account to user `ACH-US` node.\n\n##3. OAuth Platform User\n\nYour user is ready to receive money from your platform Synapse node, however there are a few steps to take before you can send money from your platform node.\n\nIn order to create a transaction from your platform `DEPOSIT-US` node to your user's `ACH-US` node, you need to perform a `GET` on your platform user account.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4 \\n-H 'content-type: application/json' -H 'x-sp-gateway: client_id_5p7x3zfEglJOGcR2beTCyNAKtLnVSFBXh6vdos4k|client_secret_nP213c0wuyWIdKZRXmjHTDC0FxNBkvLoVYfi6glt' -H 'x-sp-user: |e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1'\",\n      \"language\": \"json\",\n      \"name\": \"cURL\"\n    },\n    {\n      \"code\": \"{\\n    \\\"_id\\\": \\\"59499853838454002fd0bfe4\\\",\\n    \\\"_links\\\": {\\n        \\\"self\\\": {\\n            \\\"href\\\": \\\"https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4\\\"\\n        }\\n    },\\n    \\\"client\\\": {\\n        \\\"id\\\": \\\"589acd9ecb3cd400fa75ac06\\\",\\n        \\\"name\\\": \\\"SynapseFI\\\"\\n    },\\n    \\\"doc_status\\\": {\\n        \\\"physical_doc\\\": \\\"MISSING|INVALID\\\",\\n        \\\"virtual_doc\\\": \\\"MISSING|INVALID\\\"\\n    },\\n    \\\"documents\\\": [],\\n    \\\"emails\\\": [],\\n    \\\"extra\\\": {\\n        \\\"cip_tag\\\": 1,\\n        \\\"date_joined\\\": 1497995347197,\\n        \\\"extra_security\\\": true,\\n        \\\"is_business\\\": true,\\n        \\\"last_updated\\\": 1498004681740,\\n        \\\"public_note\\\": null,\\n        \\\"supp_id\\\": null\\n    },\\n    \\\"is_hidden\\\": false,\\n    \\\"legal_names\\\": [\\n        \\\"Test Platform\\\"\\n    ],\\n    \\\"logins\\\": [\\n        {\\n            \\\"email\\\": \\\"sankaet_ssn_only@synapsepay.com\\\",\\n            \\\"scope\\\": \\\"READ_AND_WRITE\\\"\\n        }\\n    ],\\n    \\\"permission\\\": \\\"UNVERIFIED\\\",\\n    \\\"phone_numbers\\\": [\\n        \\\"901-942-8167\\\"\\n    ],\\n    \\\"photos\\\": [],\\n    \\\"refresh_token\\\": \\\"refresh_NR3YOKwy7ucbrx1BChdiZgoAjtzLmpPEF0k4TX8n\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n From here, you will be able to capture your `refresh_token` and then perform OAuth on your platform account.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST https://uat-api.synapsefi.com/v3.1/oauth/59499853838454002fd0bfe4 \\n-H 'content-type: application/json' -H 'x-sp-gateway: client_id_5p7x3zfEglJOGcR2beTCyNAKtLnVSFBXh6vdos4k|client_secret_nP213c0wuyWIdKZRXmjHTDC0FxNBkvLoVYfi6glt' -H 'x-sp-user: |e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' -d '{\\n    \\\"refresh_token\\\":\\\"refresh_NR3YOKwy7ucbrx1BChdiZgoAjtzLmpPEF0k4TX8n\\\"\\n}'\",\n      \"language\": \"json\",\n      \"name\": \"cURL\"\n    },\n    {\n      \"code\": \"{\\n    \\\"client_id\\\": \\\"5949989f23dbf000229bdbaf\\\",\\n    \\\"client_name\\\": \\\"Test Platform\\\",\\n    \\\"expires_at\\\": \\\"1498015271\\\",\\n    \\\"expires_in\\\": \\\"7200\\\",\\n    \\\"oauth_key\\\": \\\"oauth_81rPlhbif6oeA4RgYUWkuB2x9SzwpJKEcmLIq7T5\\\",\\n    \\\"refresh_expires_in\\\": 6,\\n    \\\"refresh_token\\\": \\\"refresh_NR3YOKwy7ucbrx1BChdiZgoAjtzLmpPEF0k4TX8n\\\",\\n    \\\"scope\\\": [\\n        \\\"USER|PATCH\\\",\\n        \\\"USER|GET\\\",\\n        \\\"NODES|POST\\\",\\n        \\\"NODES|GET\\\",\\n        \\\"NODE|GET\\\",\\n        \\\"NODE|PATCH\\\",\\n        \\\"NODE|DELETE\\\",\\n        \\\"TRANS|POST\\\",\\n        \\\"TRANS|GET\\\",\\n        \\\"TRAN|GET\\\",\\n        \\\"TRAN|PATCH\\\",\\n        \\\"TRAN|DELETE\\\"\\n    ],\\n    \\\"user_id\\\": \\\"59499853838454002fd0bfe4\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nFrom the response, you need to capture the `oauth_key` to make further requests on your platform's behalf.\n\n##4. CREATE TRANSACTION\n\nYou will need your platform `DEPOSIT-US` node `_id` for this, which is easily located on the dashboard.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4/nodes/5949ca4f4d1d6200373101f8/trans -H 'content-type: application/json' -H 'x-sp-user: oauth_81rPlhbif6oeA4RgYUWkuB2x9SzwpJKEcmLIq7T5|e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' -d '{\\n  \\\"to\\\": {\\n    \\\"type\\\": \\\"ACH-US\\\",\\n    \\\"id\\\": \\\"5949c6a14d1d6200373101f0\\\"\\n  },\\n  \\\"amount\\\": {\\n    \\\"amount\\\": 20.1,\\n    \\\"currency\\\": \\\"USD\\\"\\n  },\\n  \\\"extra\\\": {\\n    \\\"ip\\\": \\\"192.168.0.1\\\"\\n  }\\n}'\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"{\\n    \\\"_id\\\": \\\"5949cb572f889600352ec8da\\\",\\n    \\\"_links\\\": {\\n        \\\"self\\\": {\\n            \\\"href\\\": \\\"https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4/nodes/5949ca4f4d1d6200373101f8/trans/5949cb572f889600352ec8da\\\"\\n        }\\n    },\\n    \\\"_v\\\": 2,\\n    \\\"amount\\\": {\\n        \\\"amount\\\": 20.1,\\n        \\\"currency\\\": \\\"USD\\\"\\n    },\\n    \\\"client\\\": {\\n        \\\"id\\\": \\\"5949989f23dbf000229bdbaf\\\",\\n        \\\"name\\\": \\\"Test Platform\\\"\\n    },\\n    \\\"extra\\\": {\\n        \\\"created_on\\\": 1498008407476,\\n        \\\"ip\\\": \\\"192.168.0.1\\\",\\n        \\\"latlon\\\": \\\"0,0\\\",\\n        \\\"note\\\": \\\"\\\",\\n        \\\"process_on\\\": 1498008407476,\\n        \\\"supp_id\\\": \\\"\\\"\\n    },\\n    \\\"fees\\\": [\\n        {\\n            \\\"fee\\\": 0,\\n            \\\"note\\\": \\\"Facilitator Fee\\\",\\n            \\\"to\\\": {\\n                \\\"id\\\": \\\"None\\\"\\n            }\\n        }\\n    ],\\n    \\\"from\\\": {\\n        \\\"id\\\": \\\"5949ca4f4d1d6200373101f8\\\",\\n        \\\"nickname\\\": \\\"My Checking\\\",\\n        \\\"type\\\": \\\"DEPOSIT-US\\\",\\n        \\\"user\\\": {\\n            \\\"_id\\\": \\\"59499853838454002fd0bfe4\\\",\\n            \\\"legal_names\\\": []\\n        }\\n    },\\n    \\\"recent_status\\\": {\\n        \\\"date\\\": 1498008407476,\\n        \\\"note\\\": \\\"Transaction Created.\\\",\\n        \\\"status\\\": \\\"CREATED\\\",\\n        \\\"status_id\\\": \\\"1\\\"\\n    },\\n    \\\"timeline\\\": [\\n        {\\n            \\\"date\\\": 1498008407476,\\n            \\\"note\\\": \\\"Transaction Created.\\\",\\n            \\\"status\\\": \\\"CREATED\\\",\\n            \\\"status_id\\\": \\\"1\\\"\\n        }\\n    ],\\n    \\\"to\\\": {\\n        \\\"id\\\": \\\"5949c6a14d1d6200373101f0\\\",\\n        \\\"nickname\\\": \\\"\\\",\\n        \\\"type\\\": \\\"ACH-US\\\",\\n        \\\"user\\\": {\\n            \\\"_id\\\": \\\"\\\",\\n            \\\"legal_names\\\": []\\n        }\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThat's it! Now you have a basic payout application working with Synapse. This is the bare bones version. If you have any questions, please [contact us](doc:contact-us) and we will be more than happy to assist.","excerpt":"Common Flow for Payout Platforms","slug":"payout-flow","type":"basic","title":"Payout Flow"}

Payout Flow

Common Flow for Payout Platforms

Onboarding users (KYC) and payment flows are customized for every platform. We recommend [contacting us](doc:contact-us) before you start developing against our APIs. But if you are curious and still want to test out our APIs, this common flow can help. The payout flow is ideal for applications that want to send money to their users. This flow will show you how to create users, add KYC, open subaccounts and make transfers. [block:image] { "images": [ { "image": [ "https://files.readme.io/36b5715-Untitled_Diagram_11.png", "Untitled Diagram (11).png", 341, 61, "#191919" ], "border": false, "sizing": "smart", "caption": "" } ] } [/block] ## 1. CREATE USER ACCOUNT AND ADD KYC [block:code] { "codes": [ { "code": "curl -X POST https://uat-api.synapsefi.com/v3.1/users -H 'content-type: application/json' -H 'x-sp-gateway: client_id_5p7x3zfEglJOGcR2beTCyNAKtLnVSFBXh6vdos4k|client_secret_nP213c0wuyWIdKZRXmjHTDC0FxNBkvLoVYfi6glt' -H 'x-sp-user: |e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' \n -d '{\n \"logins\": [\n {\n \"email\": \"test@synapsepay.com\"\n }\n ],\n \"phone_numbers\": [\n \"901.111.1111\",\n \"test@synapsepay.com\"\n ],\n \"legal_names\": [\n \"Test User\"\n ],\n \"documents\":[{\n \"email\":\"test@synapsepay.com\",\n \"phone_number\":\"901.111.1111\",\n \"ip\":\"::1\",\n \"name\":\"Test User\",\n \"alias\":\"Test\",\n \"entity_type\":\"M\",\n \"entity_scope\":\"Arts & Entertainment\",\n \"day\":2,\n \"month\":5,\n \"year\":1989,\n \"address_street\":\"1 Market St\",\n \"address_city\":\"SF\",\n \"address_subdivision\":\"CA\",\n \"address_postal_code\":\"94114\",\n \"address_country_code\":\"US\"\n }],\n \"extra\": {\n \"supp_id\": \"122eddfgbeafrfvbbb\",\n \"cip_tag\":1,\n \"is_business\": false\n }\n}'", "language": "curl" }, { "code": "{\n \"_id\": \"59499bc6838454002fd0c096\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://uat-api.synapsefi.com/v3.1/users/59499bc6838454002fd0c096\"\n }\n },\n \"client\": {\n \"id\": \"5949989f23dbf000229bdbaf\",\n \"name\": \"Test Platform\"\n },\n \"doc_status\": {\n \"physical_doc\": \"MISSING|INVALID\",\n \"virtual_doc\": \"MISSING|INVALID\"\n },\n \"documents\": [\n {\n \"id\": \"dcd19da5fb2470984d0e316fb5551269e65c109730b0b45b32a8bb1eb83d6a72\",\n \"name\": \"Test User\",\n \"permission_scope\": \"UNVERIFIED\",\n \"physical_docs\": [],\n \"social_docs\": [\n {\n \"document_type\": \"IP\",\n \"id\": \"28d9177b22c127d9a51d8903893864accf6e553ac326704a4c0d585eaad2516a\",\n \"last_updated\": 1497996229732,\n \"status\": \"SUBMITTED|VALID\"\n },\n {\n \"document_type\": \"PHONE_NUMBER\",\n \"id\": \"fda60784d6375bc44edafaaeae149626c4c13dcb92e85a2a7a00eec2cdfd2b6f\",\n \"last_updated\": 1497996229222,\n \"status\": \"SUBMITTED|VALID\"\n },\n {\n \"document_type\": \"EMAIL\",\n \"id\": \"b886811ff9cbc150065c65eb5295951ac624e3a63e57d5e016cfddc03904f46b\",\n \"last_updated\": 1497996228710,\n \"status\": \"SUBMITTED|VALID\"\n }\n ],\n \"virtual_docs\": [\n {\n \"document_type\": \"SSN\",\n \"id\": \"ee596c2896dddc19b76c07a184fe7d3cf5a04b8e94b9108190cac7890739017f\",\n \"last_updated\": 1497996228195,\n \"status\": \"SUBMITTED|VALID\"\n }\n ]\n }\n ],\n \"emails\": [],\n \"extra\": {\n \"cip_tag\": 1,\n \"date_joined\": 1497996227163,\n \"extra_security\": false,\n \"is_business\": false,\n \"last_updated\": 1497996227163,\n \"public_note\": null,\n \"supp_id\": \"122eddfgbeafrfvbbb\"\n },\n \"is_hidden\": false,\n \"legal_names\": [\n \"Test User\"\n ],\n \"logins\": [\n {\n \"email\": \"test@synapsepay.com\",\n \"scope\": \"READ_AND_WRITE\"\n }\n ],\n \"permission\": \"UNVERIFIED\",\n \"phone_numbers\": [\n \"test@synapsepay.com\",\n \"901.111.1111\"\n ],\n \"photos\": [],\n \"refresh_token\": \"refresh_FBCt0DOU9NvcfKpe3lbr7ghisaoq2ImduPERx4nW\"\n}", "language": "json", "name": "Response" } ] } [/block] In the response, you get back an `_id` associated with the user. You should store this `_id`. In addition, the `refresh_token` is included in the response which will be used to generate OAuth access, which allows you to perform operations on behalf of the user. [block:callout] { "type": "info", "body": "User verification is async. If you do `GET` user after the `POST` user API call and all documents have been submitted and verified, the user will have `RECEIVE` permissions. For a user to be able to send funds to the platform, their account permissions need to be `RECEIVE`.", "title": "Asynchronous User Verification" } [/block] ### OAuth User: If you are using one of the Client libraries, this step is not required because the libraries automatically handle OAuth after the user is created. [block:code] { "codes": [ { "code": "curl -X POST -H \"Content-Type: application/json\" -H \"X-SP-GATEWAY: e3f19e4bd4022c86e7f2|11c94ba6bad74d24a0158bc707f0fc19a86dc08f\" -H \"X-SP-USER-IP: 107.170.246.225\" -H \"X-SP-USER: |e716990e50b67a1177736960b6357524b22090ccab093d068b3d7a18dbde3f4c\" -d '{\n \"refresh_token\": \"refresh-3a09773f-388e-472b-ad1e-fccba7c2f152\"\n}' \"https://sandbox.synapsepay.com/api/3/oauth/57e468f086c2733736c13314\"", "language": "curl" }, { "code": "{\n \"expires_at\": \"1474594065\",\n \"expires_in\": \"7117\",\n \"oauth_key\": \"oauth-e8115f89-0153-4162-b024-36669ece4796\",\n \"refresh_expires_in\": 19,\n \"refresh_token\": \"refresh-3a09773f-388e-472b-ad1e-fccba7c2f152\"\n}", "language": "json", "name": "Response" } ] } [/block] From the response, you need to capture the `oauth_key` to make further requests on the user's behalf. ##2. LINK EXTERNAL ACCOUNT In this step we will allow the user to link an external bank account by using their account and routing number. [block:code] { "codes": [ { "code": "curl -X POST https://uat-api.synapsefi.com/v3.1/users/59499bc6838454002fd0c096/nodes -H 'content-type: application/json' -H 'postman-token: 3c4de184-81d0-3172-3be0-64f94a290f66' -H 'x-sp-user: oauth_ixp3DgkQatY7jXy50KqMsBmUAWVFouLS02EwnGJd|e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' -d '{\n \"type\": \"ACH-US\",\n \"info\": {\n \"nickname\": \"Fake Account\",\n \"account_num\": \"1232225674134\",\n \"routing_num\": \"051000017\",\n \"type\": \"PERSONAL\",\n \"class\": \"CHECKING\"\n }\n}'", "language": "curl" }, { "code": "{\n \"error_code\": \"0\",\n \"http_code\": \"200\",\n \"limit\": 20,\n \"node_count\": 1,\n \"nodes\": [\n {\n \"_id\": \"5949c6a14d1d6200373101f0\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://uat-api.synapsefi.com/v3.1/users/59499bc6838454002fd0c096/nodes/5949c6a14d1d6200373101f0\"\n }\n },\n \"allowed\": \"CREDIT\",\n \"client\": {\n \"id\": \"5949989f23dbf000229bdbaf\",\n \"name\": \"Test Platform\"\n },\n \"extra\": {\n \"other\": {},\n \"supp_id\": \"\"\n },\n \"info\": {\n \"account_num\": \"4134\",\n \"address\": \"8001 VILLA PARK DRIVE, HENRICO, VA, US\",\n \"balance\": {\n \"amount\": \"0.00\",\n \"currency\": \"USD\"\n },\n \"bank_long_name\": \"BANK OF AMERICA\",\n \"bank_name\": \"BANK OF AMERICA\",\n \"class\": \"CHECKING\",\n \"match_info\": {\n \"email_match\": \"not_found\",\n \"name_match\": \"not_found\",\n \"phonenumber_match\": \"not_found\"\n },\n \"name_on_account\": \" \",\n \"nickname\": \"Fake Account\",\n \"routing_num\": \"0017\",\n \"type\": \"PERSONAL\"\n },\n \"is_active\": true,\n \"timeline\": [\n {\n \"date\": 1498007200994,\n \"note\": \"Node created.\"\n }\n ],\n \"type\": \"ACH-US\",\n \"user_id\": \"59499bc6838454002fd0c096\"\n }\n ],\n \"page_count\": 1,\n \"success\": true\n}", "language": "json", "name": "Response" } ] } [/block] Since the user is only receiving funds, micro-deposit verification is not required since the user's node has `CREDIT` permissions already. From the response, you need to capture the `_id`. Now the user's external account is ready to receive funds. Both your user and your platform nodes are created. The next step is for you to create a transaction going your Platform's deposit account to user `ACH-US` node. ##3. OAuth Platform User Your user is ready to receive money from your platform Synapse node, however there are a few steps to take before you can send money from your platform node. In order to create a transaction from your platform `DEPOSIT-US` node to your user's `ACH-US` node, you need to perform a `GET` on your platform user account. [block:code] { "codes": [ { "code": "curl -X GET https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4 \n-H 'content-type: application/json' -H 'x-sp-gateway: client_id_5p7x3zfEglJOGcR2beTCyNAKtLnVSFBXh6vdos4k|client_secret_nP213c0wuyWIdKZRXmjHTDC0FxNBkvLoVYfi6glt' -H 'x-sp-user: |e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1'", "language": "json", "name": "cURL" }, { "code": "{\n \"_id\": \"59499853838454002fd0bfe4\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4\"\n }\n },\n \"client\": {\n \"id\": \"589acd9ecb3cd400fa75ac06\",\n \"name\": \"SynapseFI\"\n },\n \"doc_status\": {\n \"physical_doc\": \"MISSING|INVALID\",\n \"virtual_doc\": \"MISSING|INVALID\"\n },\n \"documents\": [],\n \"emails\": [],\n \"extra\": {\n \"cip_tag\": 1,\n \"date_joined\": 1497995347197,\n \"extra_security\": true,\n \"is_business\": true,\n \"last_updated\": 1498004681740,\n \"public_note\": null,\n \"supp_id\": null\n },\n \"is_hidden\": false,\n \"legal_names\": [\n \"Test Platform\"\n ],\n \"logins\": [\n {\n \"email\": \"sankaet_ssn_only@synapsepay.com\",\n \"scope\": \"READ_AND_WRITE\"\n }\n ],\n \"permission\": \"UNVERIFIED\",\n \"phone_numbers\": [\n \"901-942-8167\"\n ],\n \"photos\": [],\n \"refresh_token\": \"refresh_NR3YOKwy7ucbrx1BChdiZgoAjtzLmpPEF0k4TX8n\"\n}", "language": "json", "name": "Response" } ] } [/block] From here, you will be able to capture your `refresh_token` and then perform OAuth on your platform account. [block:code] { "codes": [ { "code": "curl -X POST https://uat-api.synapsefi.com/v3.1/oauth/59499853838454002fd0bfe4 \n-H 'content-type: application/json' -H 'x-sp-gateway: client_id_5p7x3zfEglJOGcR2beTCyNAKtLnVSFBXh6vdos4k|client_secret_nP213c0wuyWIdKZRXmjHTDC0FxNBkvLoVYfi6glt' -H 'x-sp-user: |e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' -d '{\n \"refresh_token\":\"refresh_NR3YOKwy7ucbrx1BChdiZgoAjtzLmpPEF0k4TX8n\"\n}'", "language": "json", "name": "cURL" }, { "code": "{\n \"client_id\": \"5949989f23dbf000229bdbaf\",\n \"client_name\": \"Test Platform\",\n \"expires_at\": \"1498015271\",\n \"expires_in\": \"7200\",\n \"oauth_key\": \"oauth_81rPlhbif6oeA4RgYUWkuB2x9SzwpJKEcmLIq7T5\",\n \"refresh_expires_in\": 6,\n \"refresh_token\": \"refresh_NR3YOKwy7ucbrx1BChdiZgoAjtzLmpPEF0k4TX8n\",\n \"scope\": [\n \"USER|PATCH\",\n \"USER|GET\",\n \"NODES|POST\",\n \"NODES|GET\",\n \"NODE|GET\",\n \"NODE|PATCH\",\n \"NODE|DELETE\",\n \"TRANS|POST\",\n \"TRANS|GET\",\n \"TRAN|GET\",\n \"TRAN|PATCH\",\n \"TRAN|DELETE\"\n ],\n \"user_id\": \"59499853838454002fd0bfe4\"\n}", "language": "json", "name": "Response" } ] } [/block] From the response, you need to capture the `oauth_key` to make further requests on your platform's behalf. ##4. CREATE TRANSACTION You will need your platform `DEPOSIT-US` node `_id` for this, which is easily located on the dashboard. [block:code] { "codes": [ { "code": "curl -X POST https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4/nodes/5949ca4f4d1d6200373101f8/trans -H 'content-type: application/json' -H 'x-sp-user: oauth_81rPlhbif6oeA4RgYUWkuB2x9SzwpJKEcmLIq7T5|e83cf6ddcf778e37bfe3d48fc78a6502062fc1030449628c699ef3c4ffa6f9a2000b8acc3c4c0addd8013285bb52c89e5267b628ca02fa84a6d71fe186b7cd5d' -H 'x-sp-user-ip: 127.0.0.1' -d '{\n \"to\": {\n \"type\": \"ACH-US\",\n \"id\": \"5949c6a14d1d6200373101f0\"\n },\n \"amount\": {\n \"amount\": 20.1,\n \"currency\": \"USD\"\n },\n \"extra\": {\n \"ip\": \"192.168.0.1\"\n }\n}'", "language": "curl" }, { "code": "{\n \"_id\": \"5949cb572f889600352ec8da\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://uat-api.synapsefi.com/v3.1/users/59499853838454002fd0bfe4/nodes/5949ca4f4d1d6200373101f8/trans/5949cb572f889600352ec8da\"\n }\n },\n \"_v\": 2,\n \"amount\": {\n \"amount\": 20.1,\n \"currency\": \"USD\"\n },\n \"client\": {\n \"id\": \"5949989f23dbf000229bdbaf\",\n \"name\": \"Test Platform\"\n },\n \"extra\": {\n \"created_on\": 1498008407476,\n \"ip\": \"192.168.0.1\",\n \"latlon\": \"0,0\",\n \"note\": \"\",\n \"process_on\": 1498008407476,\n \"supp_id\": \"\"\n },\n \"fees\": [\n {\n \"fee\": 0,\n \"note\": \"Facilitator Fee\",\n \"to\": {\n \"id\": \"None\"\n }\n }\n ],\n \"from\": {\n \"id\": \"5949ca4f4d1d6200373101f8\",\n \"nickname\": \"My Checking\",\n \"type\": \"DEPOSIT-US\",\n \"user\": {\n \"_id\": \"59499853838454002fd0bfe4\",\n \"legal_names\": []\n }\n },\n \"recent_status\": {\n \"date\": 1498008407476,\n \"note\": \"Transaction Created.\",\n \"status\": \"CREATED\",\n \"status_id\": \"1\"\n },\n \"timeline\": [\n {\n \"date\": 1498008407476,\n \"note\": \"Transaction Created.\",\n \"status\": \"CREATED\",\n \"status_id\": \"1\"\n }\n ],\n \"to\": {\n \"id\": \"5949c6a14d1d6200373101f0\",\n \"nickname\": \"\",\n \"type\": \"ACH-US\",\n \"user\": {\n \"_id\": \"\",\n \"legal_names\": []\n }\n }\n}", "language": "json", "name": "Response" } ] } [/block] That's it! Now you have a basic payout application working with Synapse. This is the bare bones version. If you have any questions, please [contact us](doc:contact-us) and we will be more than happy to assist.