Merge pull request #24 from PaystackOSS/dev

Dev

Author: damilola-paystack

dist/betting.yaml

@@ -1,7 +1,17 @@
 openapi: 3.0.1
 info:
   title: Create a wallet app
-  description: The OpenAPI specification for creating a wallet application using the Paystack API
+  description: |-
+    The OpenAPI specification for creating a wallet application using the [Paystack API](https://paystack.com/docs/api/).
+    ### Prerequisites
+    1. Sign up on [Paystack](https://paystack.com/signup) to get your secret API key
+    2. Set your API key as an environment variable on [Postman](https://learning.postman.com/docs/sending-requests/variables/)
+
+    After setting up your secret API key, use the [Customers API](https://paystack.com/docs/api/#customer) to create and validate a customer.  You then assign a [Dedicated Virtual Account](https://paystack.com/docs/payments/dedicated-virtual-accounts) to the customer. 
+
+    Transfers in this case refer to moving money to bank accounts and mobile money accounts using our [Transfers API](https://paystack.com/docs/transfers) rather than other wallet users.
+
+    *Dedicated Virtual Account is currently available for [registered businesses](https://support.paystack.com/hc/en-us/articles/360009881220-How-do-I-activate-my-Paystack-Registered-Business-) in Nigeria.*
   version: 1.0.0
 servers:
   - url: 'https://api.paystack.co'
@@ -27,15 +37,51 @@ paths:
                 - $ref: '#/components/schemas/Customer/allOf/1'
       responses:
         '200':
-          description: Request successful
+          description: Customer Created
           content:
             application/json:
               schema:
                 $ref: '#/components/responses/Ok/content/application~1json/schema'
+              examples:
+                Create Customer:
+                  value:
+                    status: true
+                    message: Customer created
+                    data:
+                      transactions: []
+                      subscriptions: []
+                      authorizations: []
+                      email: [email protected]
+                      first_name: Some
+                      last_name: Body
+                      phone: '+2348123456789'
+                      integration: 463433
+                      domain: test
+                      metadata: {}
+                      customer_code: CUS_pztcpsx5kng2fbk
+                      risk_action: default
+                      id: 95485991
+                      createdAt: '2022-09-20T12:52:10.583Z'
+                      updatedAt: '2022-09-20T12:52:10.583Z'
+                      identified: false
+                      identifications: []
         '401':
           description: Unauthorized operation
           content:
             application/json:
+              examples:
+                No-Authorization-Header:
+                  value:
+                    status: false
+                    message: No Authorization Header was found
+                Bad-Authorization-Header:
+                  value:
+                    status: false
+                    message: 'Format is Authorization Bearer [secret key]'
+                Invalid-Key:
+                  value:
+                    status: false
+                    message: Invalid key
               schema:
                 type: object
                 properties:
@@ -68,16 +114,16 @@ paths:
               $ref: '#/components/schemas/Customer/allOf/4'
       responses:
         '202':
-          description: Request accepted for processing
+          description: Customer Validation
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  status:
-                    type: boolean
-                  message:
-                    type: string
+                $ref: '#/components/responses/Ok/content/application~1json/schema'
+              examples:
+                Validate Customer:
+                  value:
+                    status: true
+                    message: Customer Identification in progress
         '401':
           $ref: '#/paths/~1customer/post/responses/401'
         default:
@@ -102,18 +148,60 @@ paths:
                 customer:
                   description: Customer ID or code
                   type: string
+                  example: CUS_abc123der
                 preferred_bank:
                   description: 'The bank slug for preferred bank. To get a list of available banks, use the List Providers endpoint'
                   type: string
+                  example: wema-bank
                 subaccount:
                   description: Subaccount code of the account you want to split the transaction with
                   type: string
+                  example: ACCT_123455asdin
                 split_code:
                   description: Split code consisting of the lists of accounts you want to split the transaction with
                   type: string
+                  example: SPL_123asbde
       responses:
         '200':
-          $ref: '#/paths/~1customer/post/responses/200'
+          description: Creation Successful
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/responses/Ok/content/application~1json/schema'
+              examples:
+                Create Dedicated Account:
+                  value:
+                    status: true
+                    message: NUBAN successfully created
+                    data:
+                      bank:
+                        name: Wema Bank
+                        id: 20
+                        slug: wema-bank
+                      account_name: KAROKART / RHODA CHURCH
+                      account_number: 9930000737
+                      assigned: true
+                      currency: NGN
+                      metadata: null
+                      active: true
+                      id: 253
+                      created_at: 2019-12-12T12:39:04.000Z
+                      updated_at: 2020-01-06T15:51:24.000Z
+                      assignment:
+                        integration: 100043
+                        assignee_id: 7454289
+                        assignee_type: Customer
+                        expired: false
+                        account_type: PAY-WITH-TRANSFER-RECURRING
+                        assigned_at: 2020-01-06T15:51:24.764Z
+                      customer:
+                        id: 7454289
+                        first_name: RHODA
+                        last_name: CHURCH
+                        email: [email protected]
+                        customer_code: CUS_kpb3qj71u1m0rw8
+                        phone: 2349053267565
+                        risk_action: default
         '401':
           $ref: '#/paths/~1customer/post/responses/401'
         default:
@@ -139,36 +227,78 @@ paths:
                 - bank_code
               properties:
                 type:
-                  description: Recipient Type (Only nuban at this time)
+                  description: 'Recipient Type - nuban for NGN, mobile_money for MOMO in GHS, basa for ZAR and authorization for all.'
                   type: string
+                  enum:
+                    - nuban
+                    - mobile_money
+                    - basa
+                    - authorization
                 name:
                   description: Recipient's name
                   type: string
+                  example: Ada Lovelace
                 account_number:
                   description: Recipient's bank account number
                   type: string
+                  example: '0000000000'
                 bank_code:
                   description: Recipient's bank code. You can get the list of Bank Codes by calling the List Banks endpoint
                   type: string
+                  example: '011'
                 description:
                   description: A description for this recipient
                   type: string
+                  example: Keeps our servers running
                 currency:
                   description: Currency for the account receiving the transfer
                   type: string
+                  enum:
+                    - NGN
+                    - GHS
+                    - ZAR
                 authorization_code:
                   description: An authorization code from a previous transaction
                   type: string
+                  example: AUTH_CODE
                 metadata:
                   description: Stringified JSON object of custom data
                   type: string
+                  example: |
+                    {referrer_id: 123}
       responses:
         '201':
-          description: Resource created
+          description: Transfer Recipient Created
           content:
             application/json:
               schema:
                 $ref: '#/components/responses/Ok/content/application~1json/schema'
+              examples:
+                Create Customer:
+                  value:
+                    status: true
+                    message: Transfer recipient created successfully
+                    data:
+                      active: true
+                      createdAt: 2022-09-16T08:31:43.321Z
+                      currency: NGN
+                      domain: live
+                      id: 38770134
+                      integration: 463433
+                      metadata:
+                        referrer_id: 123
+                      name: Ada Lovelace
+                      recipient_code: RCP_2fl8jmb2v3kbleb
+                      type: nuban
+                      updatedAt: 2022-09-16T08:31:43.321Z
+                      is_deleted: false
+                      isDeleted: false
+                      details:
+                        authorization_code: null
+                        account_number: 0
+                        account_name: Doe Jane Loren
+                        bank_code: 9
+                        bank_name: First Bank of Nigeria
         '401':
           $ref: '#/paths/~1customer/post/responses/401'
         default:
@@ -195,15 +325,19 @@ paths:
                 source:
                   description: Where should we transfer from? Only balance is allowed for now
                   type: string
+                  example: balance
                 amount:
-                  description: Amount to transfer in kobo if currency is NGN and pesewas if currency is GHS.
-                  type: string
+                  description: Amount to transfer in kobo if currency is NGN. pesewas if currency is GHS and cents for ZAR.
+                  type: integer
+                  example: 10234
                 recipient:
                   description: The transfer recipient's code
                   type: string
+                  example: RCP_CODE
                 reason:
                   description: The reason or narration for the transfer.
                   type: string
+                  example: Good job
                 currency:
                   description: Specify the currency of the transfer. Defaults to NGN.
                   type: string
@@ -212,9 +346,33 @@ paths:
                     If specified, the field should be a unique identifier (in lowercase) for the object. 
                     Only -,_ and alphanumeric characters are allowed.
                   type: string
+                  example: Transfer-123_unique
       responses:
         '200':
-          $ref: '#/paths/~1customer/post/responses/200'
+          description: Request successful
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/responses/Ok/content/application~1json/schema'
+              examples:
+                Initiate Transfer:
+                  value:
+                    status: true
+                    message: Transfer has been queued
+                    data:
+                      reference: on5hyz9poe
+                      integration: 428626
+                      domain: test
+                      amount: 3794800
+                      currency: NGN
+                      source: balance
+                      reason: Holiday Flexing
+                      recipient: 6788170
+                      status: success
+                      transfer_code: TRF_fiyxvgkh71e717b
+                      id: 23070321
+                      createdAt: 2020-05-13T14:22:49.687Z
+                      updatedAt: 2020-05-13T14:22:49.687Z
         '401':
           $ref: '#/paths/~1customer/post/responses/401'
         default:
@@ -239,12 +397,15 @@ components:
             first_name:
               description: Customer's first name
               type: string
+              example: Some
             last_name:
               description: Customer's last name
               type: string
+              example: Body
             phone:
               description: Customer's phone number
               type: string
+              example: '+2348123456789'
             metadata:
               description: Stringified JSON object of custom data
               type: string
@@ -288,18 +449,27 @@ components:
             country:
               description: Two-letter country code of identification issuer
               type: string
+              example: NG
             bvn:
               description: Customer's Bank Verification Number
-              type: string
+              type: integer
+              example: 0123456789
             bank_code:
               description: 'You can get the list of bank codes by calling the List Banks endpoint (https://api.paystack.co/bank).'
               type: string
+              example: '007'
             account_number:
               description: Customer's bank account number.
               type: string
-            value:
-              description: Customer's identification number. Required if type is bvn
+              example: '0111111111'
+            first_name:
+              description: Customer's first name
+              type: string
+              example: Uchenna
+            last_name:
+              description: Customer's last name
               type: string
+              example: Okoro
     Error:
       type: object
       properties:

dist/lending.yaml

@@ -0,0 +1,21 @@
+value:
+  status: true
+  message: Customer created
+  data:
+    transactions: []
+    subscriptions: []
+    authorizations: []
+    email: [email protected]
+    first_name: Some
+    last_name: Body
+    phone: "+2348123456789"
+    integration: 463433
+    domain: test
+    metadata: {}
+    customer_code: CUS_pztcpsx5kng2fbk
+    risk_action: default
+    id: 95485991
+    createdAt: '2022-09-20T12:52:10.583Z'
+    updatedAt: '2022-09-20T12:52:10.583Z'
+    identified: false
+    identifications: []

dist/marketplace.yaml

@@ -0,0 +1,3 @@
+value:
+  status: true
+  message: Customer Identification in progress