Cash-out

This page contains details on four endpoints used to cash-out from any cUSD wallet to external e-wallets in the Philippines and twelve countries across Africa.

Authentication

The Ponto API uses API keys to authenticate requests. You can access your API key by contacting the Ponto team. These secret keys have the prefix sk_live. Be sure to keep these keys secure. Authentication to the API is performed via bearer auth. Use the header Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc when sending requests to the API.

All API requests must be made over HTTPS. API requests without authentication will fail with a 401 response code.

Once a Session has been created, the returned token should be sent with all subsequent requests to ensure the user cash out is secure. Tokens should be sent in the header x-secret. Requests without a token will fail with a 401 response code.

Create a session

POST https://api.withponto.com/v1/sessions/create

Creates a user Session. The returned token should be sent in the x-secret header in all subsequent requests. The verified boolean in the response can be used to determine if a user has already completed their KYC Profile. If verified is true, the response will also contain a profile key, which is the id of their existing KYC Profile. If verified is false, KYC information must be collected and a new Profile created before a transfer can be initiated.

Headers

Name	Type	Description
Authentication	string	API key used to authenticate requests via bearer auth.

Request Body

Name	Type	Description
timezone	string	The client timezone.
expiresAt	string	Sets an explicit expiration time for the session. Use ISO 8601 timestamp format.
email	string	An email for the user.
phoneNumber	string	A user's phone number in E.164 number format: [phone].

200 Session created successfully. If the user if verified, they have a KYC profile on file and can immediately initiate a transfer.

{
  token: "MwIGQK4xYsKY5J7teiOg8lsm",
  verified: true, // If false, KYC must be run to initiate a transfer
  profile: 'prof_1HCxCjB6EV6qApAtzFgd',
  expiresAt: '2021-03-24T07:43:37.102Z'
}

422 Session data was not formatted correctly.

Create a profile

POST https://api.withponto.com/v1/profiles/create

Creates a know-your-customer (KYC) profile for a user with three parts: Contact Info, Address, and ID. Business Infocan be passed in place of Contact Info as a mutually exclusive alternative. A Profile can be created all at once or built in parts by calling the endpoint and passing in an existing profile id - though one of each profile must contain either Contact Info or Business Info as a required building block. Each part will be verified with a third-party service to complete the KYC process. Profile must be returned with a verified: true flag to be used for transactions.

Headers

Name	Type	Description
x-secret	string	The user Session token.
Authorization	string	The API key.

Request Body

Name	Type	Description
timezone	string	Client timezone.
business	string	A dictionary containing the business contact information. Should be used in place of contact if the profile is for a business.
id	string	The id of an existing unverified profile to complete with the passed information. Note that the profile must be unverified, as verified profiles cannot be edited.
contact	object	A dictionary of the user contact information. If the profile is for a business, business should be used to in place of this field.
identityDocument	object	A dictionary containing data for the verification document and Base64 encoded images of the document.
address	object	A dictionary of the user' or business' address.

200 A profile object.

{
  id: 'prof_D33gJnuVt5qCmpJt',
  business: null,
  contact: {
    email: '[email protected]',
    phoneNumber: '[phone]'
  },
  identityDocument: {
    type: 'driving_license',
    number: 'A4023495', 
    givenName: 'Andres',
    middleName: null,
    familyName: 'Bonta',
    dateOfBirth: '1998-07-26',
    issueDate: '2021-03-25',
    expirationDate: '2028-03-25',
    frontPhoto: 'data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEU...',
    backPhoto: 'data:image/jpeg;base64,mNlhCKlNCbIJ0AUkIPRXoV...',
    personalPhoto: 'data:image/jpeg;base64,A1IDdJ514b209fc61L...'
  },
  address: {
    streetNumber: '1671',
    streetName: 'Sta. Cruz Alvarez',
    streetType: 'St',
    buildingName: 'MBC Building',
    addressType: 'building',
    addressTypeIdentifier: null,
    localMunicipality: 'Santa Cruz',
    city: 'Manila',
    governingDistrict: 'Metro Manila',
    postalArea: '1003',
    country: 'PHL'
  },
  email: '[email protected]',
  phoneNumber: '[phone]',
  verifiedEmail: false,
  verifiedPhoneNumber: false,
  identityDocumentVerificationProvider: 'shuftiPro',
  addressVerificationProvider, 'ponto',
  verifiedBusiness: null
  verifiedContact: true,
  verifiedIdentityDocument: true,
  verifiedAddress: true,
  verified: true,
  updatedAt: '2021-03-24T07:43:37.102Z',
  createdAt: '2021-03-24T07:43:07.714Z'
}

400 Verification failures include error details.

Contact Object

Attribute	Description
email	The user's email address.
phoneNumber	The user's phone number in E.164 number format.

{
  email: '[email protected]',
  phoneNumber: '[phone]'
}

Identity Document Object

Attribute	Description
type	A string of the document type. Supported types are: driving_license, employment_id, passport, national_id, government_id, student_id, other_id
number	The document number as a string.
givenName	The user's first name.
middleName	The user's middle name.
familyName	The user's last name.
dateOfBirth	The user's birthday in ISO date format.
gender	The gender listed on the document.
issueDate	An ISO date string for the document issue date.
expirationDate	An ISO date string for the document expiration date.
frontPhoto	A base64 data url for an image of the front of the document.
backPhoto	A base64 data url for an image of the back of the document.
personalPhoto	A base64 data url for an image. PNG or JPEGs are supported. Max size is 4 MB.

{
  type: 'driving_license',
  number: 'A4023495',
  givenName: 'Andres',
  middleName: null,
  familyName: 'Bonta',
  dateOfBirth: '1998-07-26',
  issueDate: '2021-03-25',
  expirationDate: '2028-03-25',
  frontPhoto: 'data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEU...',
  backPhoto: 'data:image/jpeg;base64,mNlhCKlNCbIJ0AUkIPRXoV...',
  personalPhoto: 'data:image/jpeg;base64,A1IDdJ514b209fc61L...'
}

Address Object

Attribute	Description
streetNumber	The address street number as a string.
streetName	The street name.
streetType	The street type (e.g., Road, Street, St, Ave)
buildingName	(Optional) The name of the building.
addressType	The type of address (e.g. apartment, house, building, floor, office, suite).
addressTypeIdentifier	(Optional) The identifier within the address like the number of an apartment, suite, or floor.
localMunicipality	(Optional) A part of a town or city (e.g., a hamlet or village that appears before the town name)
city	The city name.
governingDistrict	(Optional) The state name, province name, or other local governing boundary.
postalArea	(Optional) The zip, postal code, or other postal identifier
country	The 3-letter ISO 3166 country code.

{
  streetNumber: '1671'
  streetName: 'Sta. Cruz Alvarez',
  streetType: 'St',
  buildingName: 'MBC Building',
  addressType: 'building',
  addressTypeIdentifier: null,
  localMunicipality: 'Santa Cruz',
  city: 'Manila',
  governingDistrict: 'Metro Manila',
  postalArea: '1003',
  country: 'PHL'
}

Create a transfer

POST https://api.withponto.com/v1/transfers/create

Transfer a specified amount between two wallets. Transfers are created by combining an origin wallet and profile with a recipient wallet and profile. Both origin and recipient profiles must be verified. Profiles may be the same if the user is the owner of both the origin and recipient wallets. Before funds can be sent to the recipient, the newly created transfer must be paid. The payableWalletAddress field returned by the API contains a cUSD wallet address which corresponds to the transfer. The user should be prompted to sign and send a transaction of amount originAmount to this address using the origin wallet.

Headers

Name	Type	Description
x-secret	string	The user Session token.
Authorization	string	The API key.

Request Body

Name	Type	Description
amount	integer	Amount to transfer from origin wallet to recipient wallet. A positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00). The minimum is 50 and maximum is 100,000.
originCurrency	string	The currency for amount. Accepts three-letter ISO currency codes and cryptocurrency symbols. Required only if origin wallet supports multiple currencies. Must be a supported currency.
originWallet	object	A Wallet where the transfer will originate.
originProfile	string	The id of the verified Profile for the user initiating the transfer.
recipientWallet	object	The Wallet where amount will be transferred.
recipientProfile	string	The id of the verified Profile for the user receiving the transfer. Can match originProfile id if the user is sending to another wallet they own.

200 Returns a pending transfer object.

{
    id: 'tra_KWf5GBXyPkDCk1SN',
    originAmount: 100,
    originCurrency: 'CUSD',
    originFeeAmount: 0.01,
    recipientCurrency: 'PHP',
    payableWalletAddress: '0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d',
    status: 'pending',
    statusMessage: 'Transfer is pending.',
    completedAt: null,
    updatedAt: '2021-03-24T07:43:07.714Z',
    createdAt: '2021-03-24T07:43:07.714Z'
}

Wallet Object

Attribute	Description
type	The wallet type. Supported types: valora, gcash, mpesa
accountInfo	An object containing account info for the wallet.
accountInfo.phoneNumber	The phone number associated with the wallet.

{
  type: 'gcash',
  accountInfo: {
    phoneNumber: '[phone]' 
  }
}

Send a transfer

POST https://api.withponto.com/v1/transfers/send

Once a user has sent funds to payableWalletAddress, a transfer can be sent to the recipient wallet using this endpoint.

Headers

Name	Type	Description
x-secret	string	The user Session token.
Authorization	string	The API key.

Request Body

Name	Type	Description
id	string	The transfer id to be sent.

200 Transfer completed.

{
    id: 'tra_KWf5GBXyPkDCk1SN',
    originAmount: 100,
    originCurrency: 'CUSD',
    originFeeAmount: 0.01,
    recipientFeeAmount: 0.01,
    recipientCurrency: 'PHP',
    recipientAmount: 4857.55,
    exchangeRate: 48.58,
    status: 'complete',
    statusMessage: 'Transfer successfully completed.',
    completedAt: '2021-03-24T07:43:37.102Z',
    updatedAt: '2021-03-24T07:43:37.102Z',
    createdAt: '2021-03-24T07:43:07.714Z'
}

402 Transfer could not be completed because it hadn't yet been paid.