> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawapay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Check remittance status

Get the current status of the remittance based on its `remittanceId`.


## OpenAPI

````yaml openapi_v2 get /v2/remittances/{remittanceId}
openapi: 3.0.0
info:
  title: PawaPay Merchant API V2
  description: Please find complete documentation from https://docs.pawapay.io/.
  version: v2
  x-logo:
    url: >-
      https://global-uploads.webflow.com/62824591015aa314fd308df1/6411b26596e3de3f52551c00_Logopawapay-p-500.png
    href: https://docs.pawapay.io/
    altText: PawaPay logo
servers:
  - url: https://api.sandbox.pawapay.io
    description: PawaPay Merchant API sandbox
  - url: https://api.pawapay.io
    description: PawaPay Merchant API production
security:
  - bearerAuth: []
tags:
  - name: deposits
    x-displayName: Deposits
  - name: split-payments
    x-displayName: Split Payments
  - name: checkouts
    x-displayName: Checkouts
  - name: payouts
    x-displayName: Payouts
  - name: refunds
    x-displayName: Refunds
  - name: remittances
    x-displayName: Remittances
  - name: payment-page
    x-displayName: Payment Page
  - name: toolkit
    x-displayName: Toolkit
  - name: finances
    x-displayName: Finances
paths:
  /v2/remittances/{remittanceId}:
    get:
      tags:
        - remittances
      summary: Check remittance status
      operationId: getRemittance
      parameters:
        - $ref: '#/components/parameters/RemittanceId'
      responses:
        '200':
          description: Request has been processed by PawaPay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceSearchResult'
              examples:
                COMPLETED:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: COMPLETED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      providerTransactionId: '12356789'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                ACCEPTED:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: ACCEPTED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                PROCESSING:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: PROCESSING
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                IN_RECONCILIATION:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: IN_RECONCILIATION
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                FAILED:
                  value:
                    status: FOUND
                    data:
                      remittanceId: 8917c345-4791-4285-a416-62f24b6982db
                      status: FAILED
                      amount: '123.00'
                      currency: ZMW
                      country: ZMB
                      recipient:
                        type: MMO
                        accountDetails:
                          phoneNumber: '260763456789'
                          provider: MTN_MOMO_ZMB
                      customerMessage: From ACME company
                      created: '2020-10-19T08:17:01Z'
                      failureReason:
                        failureCode: RECIPIENT_NOT_FOUND
                        failureMessage: Recipient not found
                      metadata:
                        orderId: ORD-123456789
                        customerId: customer@email.com
                NOT_FOUND:
                  value:
                    status: NOT_FOUND
        '401':
          description: >-
            Authentication failed. Make sure you have added the API token into
            the header. If using signatures, make sure they are valid.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RemittanceResponseId'
                  - $ref: '#/components/schemas/AuthenticationFailureResponse'
              examples:
                AUTHENTICATION_ERROR:
                  value:
                    remittanceId: f4401bd2-1568-4140-bf2d-eb77d2b2b639
                    status: REJECTED
                    failureReason:
                      failureCode: AUTHENTICATION_ERROR
                      failureMessage: The API token in the request is invalid.
        '403':
          description: Authorization failure. Please check your authentication token.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RemittanceResponseId'
                  - $ref: '#/components/schemas/AuthorizationFailureResponse'
              examples:
                AUTHORISATION_ERROR:
                  value:
                    remittanceId: f4401bd2-1568-4140-bf2d-eb77d2b2b639
                    status: REJECTED
                    failureReason:
                      failureCode: AUTHORISATION_ERROR
                      failureMessage: >-
                        The API token in the request is not authorised for this
                        endpoint.
        '500':
          description: An unknown failure has occurred.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/UnknownFailureResponse'
              examples:
                UNKNOWN_ERROR:
                  value:
                    failureReason:
                      failureCode: UNKNOWN_ERROR
                      failureMessage: Unable to process request due to an unknown problem.
components:
  parameters:
    RemittanceId:
      in: path
      name: remittanceId
      required: true
      description: The id of the remittance that you are performing this operation on.
      schema:
        minLength: 36
        maxLength: 36
        type: string
        format: uuid
      example: f4401bd2-1568-4140-bf2d-eb77d2b2b639
  schemas:
    RemittanceSearchResult:
      required:
        - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SearchResultStatus'
        data:
          $ref: '#/components/schemas/Remittance'
    RemittanceResponseId:
      type: object
      properties:
        remittanceId:
          $ref: '#/components/schemas/ResponsePaymentId'
    AuthenticationFailureResponse:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        status:
          type: string
          enum:
            - REJECTED
          description: The status of the response will always be `REJECTED`
          example: REJECTED
        failureReason:
          $ref: '#/components/schemas/AuthenticationFailureReason'
    AuthorizationFailureResponse:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        status:
          type: string
          enum:
            - REJECTED
          description: The status of the response will always be `REJECTED`
          example: REJECTED
        failureReason:
          $ref: '#/components/schemas/AuthorizationFailureReason'
    UnknownFailureResponse:
      required:
        - failureCode
        - failureMessage
      type: object
      properties:
        failureReason:
          type: object
          properties:
            failureCode:
              type: string
              description: >
                Reason for the failure:

                * `UNKNOWN_ERROR` - Unable to process request due to an unknown
                problem.
              example: UNKNOWN_ERROR
            failureMessage:
              type: string
              description: A description of the failure
              example: Unable to process request due to an unknown problem.
    SearchResultStatus:
      type: string
      description: |
        The result of this operation.
        - `FOUND` - The payment was found in PawaPay.
        - `NOT_FOUND` - The payment was not found in PawaPay.
      enum:
        - FOUND
        - NOT_FOUND
    Remittance:
      required:
        - remittanceId
        - status
        - amount
        - currency
        - country
        - recipient
        - created
      type: object
      properties:
        remittanceId:
          $ref: '#/components/schemas/ResponsePaymentId'
        status:
          $ref: '#/components/schemas/RemittanceStatus'
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        country:
          $ref: '#/components/schemas/Country'
        recipient:
          $ref: '#/components/schemas/RemittanceRecipient'
        sender:
          $ref: '#/components/schemas/RemittanceSender'
        customerMessage:
          $ref: '#/components/schemas/CustomerMessage'
        created:
          $ref: '#/components/schemas/CreatedTimestamp'
        providerTransactionId:
          $ref: '#/components/schemas/ProviderTransactionId'
        failureReason:
          $ref: '#/components/schemas/RemittanceFailureReason'
        metadata:
          $ref: '#/components/schemas/TransactionMetadataResponse'
    ResponsePaymentId:
      minLength: 36
      maxLength: 36
      type: string
      format: uuid
      description: >-
        The unique ID for this payment in PawaPay as specified by you during
        initiation.
      example: f4401bd2-1568-4140-bf2d-eb77d2b2b639
    AuthenticationFailureReason:
      required:
        - failureReason
      type: object
      properties:
        failureCode:
          type: string
          description: >
            Reason for the failure:

            * `NO_AUTHENTICATION` - The API token was not found in the request
            headers.

            * `AUTHENTICATION_ERROR` - The API token in the request headers is
            not valid.

            * `HTTP_SIGNATURE_ERROR` - The signature you have passed with the
            request did not pass verification.
          enum:
            - NO_AUTHENTICATION
            - AUTHENTICATION_ERROR
            - HTTP_SIGNATURE_ERROR
        failureMessage:
          type: string
          description: A description of the failure
    AuthorizationFailureReason:
      required:
        - failureReason
      type: object
      properties:
        failureCode:
          type: string
          description: >
            Reason for the failure:

            * `AUTHORISATION_ERROR` - The API Token in the request header is not
            authorised to make this request.

            * `DEPOSITS_NOT_ALLOWED` - Deposits are not enabled with the
            provider on your PawaPay account.

            * `PAYOUTS_NOT_ALLOWED` - Payouts are not enabled with the provider
            on your PawaPay account.

            * `REMITTANCES_NOT_ALLOWED` - Remittances are not enabled with the
            provider on your PawaPay account.

            * `REFUNDS_NOT_ALLOWED` - Refunds are not enabled with the provider
            on your PawaPay account.
          enum:
            - AUTHORISATION_ERROR
            - DEPOSITS_NOT_ALLOWED
            - PAYOUTS_NOT_ALLOWED
            - REMITTANCES_NOT_ALLOWED
            - REFUNDS_NOT_ALLOWED
        failureMessage:
          type: string
          description: A description of the failure
    RemittanceStatus:
      type: string
      description: >
        Possible remittance statuses: 

        * `ACCEPTED` - The remittance has been **accepted** by PawaPay for
        processing. 

        * `ENQUEUED` - The remittance has been **accepted**, but has been
        enqueued for processing later. Read more about [enqueued
        remittances](/v2/docs/remittances#handling-enqueued-remittances-and-provider-availability). 

        * `PROCESSING` - The remittance has been submitted to the provider and
        is being processed.

        * `IN_RECONCILIATION` - The remittance is being reconciled currently to
        determine it's final status.

        * `COMPLETED` - The remittance has been successfully processed. This is
        a **final status.**

        * `FAILED` - The remittance has been processed, but failed. This is a
        **final status.**. See `failureReason` for details.
      enum:
        - ACCEPTED
        - ENQUEUED
        - PROCESSING
        - IN_RECONCILIATION
        - COMPLETED
        - FAILED
    Amount:
      minLength: 1
      maxLength: 23
      type: string
      pattern: ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$
      description: >
        The amount of the payment.


        Amount must follow below requirements or the request will be
        **rejected**:

        * Not all providers support decimals. Find which ones do from
        [providers](/v2/docs/providers) or dynamically using [active
        configuration](/v2/api-reference/toolkit/active-configuration) endpoint.

        * Transaction limits apply. Find them from the [Active
        Configuration](/v2/api-reference/toolkit/active-configuration) endpoint.

        * Leading zeroes are not permitted except where the value is less than
        1. For any value less than one, one and only one leading zero must be
        supplied.
      example: '15'
    Currency:
      type: string
      description: >
        The currency in which the `amount` is specified.


        Format must be the ISO 4217 three character currency code in upper case.
        Read more from
        [Wikipedia](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).


        Find the supported currencies for the [provider](/v2/docs/providers).


        The [active
        configuration](/v2/api-reference/toolkit/active-configuration) endpoint
        has all the providers configured for your account together with the
        supported currencies.
      example: ZMW
    Country:
      type: string
      minLength: 3
      maxLength: 3
      description: >
        The country in which the payment was initiated.


        Format is ISO 3166-1 alpha-3, three character country code in upper
        case. Read more from
        [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
      example: ZMB
    RemittanceRecipient:
      description: Details about the customer who is receiving the remittance.
      required:
        - type
        - accountDetails
        - recipientDetails
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AccountDetailsType'
        accountDetails:
          $ref: '#/components/schemas/RemittanceAccountDetails'
        recipientDetails:
          $ref: '#/components/schemas/RecipientDetails'
    RemittanceSender:
      description: Details about the customer who is sending the remittance.
      required:
        - transactionDetails
        - senderDetails
      type: object
      properties:
        transactionDetails:
          $ref: '#/components/schemas/TransactionDetails'
        senderDetails:
          $ref: '#/components/schemas/SenderDetails'
    CustomerMessage:
      minLength: 4
      maxLength: 22
      type: string
      pattern: ^[a-zA-Z0-9 ]+$
      description: >
        A short narration for the transaction. 

        Depending on the 'provider', this message may be visible to the customer
        in the SMS receipt or within their transaction history.


        Defaults to your company name as registered on your PawaPay account
        trimmed to fit the length limitations.
      example: Note of 4 to 22 chars
    CreatedTimestamp:
      type: string
      description: >-
        The timestamp of when the payment was created in the PawaPay platform.
        Format defined by 'date-time' in RFC3339 section 5.6 from
        [IETF](https://tools.ietf.org/html/rfc3339#section-5.6)
      format: date-time
      example: '2020-02-21T17:32:29Z'
    ProviderTransactionId:
      type: string
      description: >-
        The unique ID for this payment assigned by the provider. The customer
        would see this ID on their SMS receipt and transaction history.
      example: ABC123
    RemittanceFailureReason:
      required:
        - failureCode
      type: object
      properties:
        failureCode:
          type: string
          description: >
            Possible remittance failure codes: 

            * `PAWAPAY_WALLET_OUT_OF_FUNDS` - Your PawaPay wallet does not have
            enough funds to complete this remittance.

            * `RECIPIENT_NOT_FOUND` - The phone number specified as the
            receipient does not belong to the provider. 

            * `WALLET_LIMIT_REACHED` - The recipient has reached a limit on
            their wallet that stops them from being able to accept this
            remittance. 

            * `MANUALLY_CANCELLED` - The remittance was enqueued and
            subsequently cancelled from the PawaPay Dashboard or through the
            [Cancel Enqueued
            Remittance](/v2/api-reference/remittances/cancel-enqueued-remittance)
            endpoint.

            * `UNSPECIFIED_FAILURE` - The provider confirmed the payment has
            failed, but did not provide any information about the reason of the
            failure.

            * `UNKNOWN_ERROR` - An unknown error has occurred.
          example: WALLET_LIMIT_REACHED
          enum:
            - PAWAPAY_WALLET_OUT_OF_FUNDS
            - RECIPIENT_NOT_FOUND
            - WALLET_LIMIT_REACHED
            - MANUALLY_CANCELLED
            - UNSPECIFIED_FAILURE
            - UNKNOWN_ERROR
        failureMessage:
          type: string
          description: Description of the reason for this failure
          example: Recipient's address is blocked
    TransactionMetadataResponse:
      description: >
        The metadata that was provided in the original initation request in a
        JSON object format.
      type: object
      properties:
        additionalProperties:
          type: string
          description: >-
            Each passed in metadata field will be a property of the metadata
            JSON object.
      example:
        orderId: ORD-123456789
        customerId: customer@email.com
    AccountDetailsType:
      type: string
      description: >-
        The type of account involved in the transaction. At the moment, only
        **MMO** is supported.
      example: MMO
      enum:
        - MMO
    RemittanceAccountDetails:
      required:
        - provider
        - phoneNumber
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        provider:
          $ref: '#/components/schemas/RemittanceProvider'
    RecipientDetails:
      required:
        - firstName
        - lastName
      type: object
      properties:
        firstName:
          type: string
          description: The first name of the recipient of this remittance.
          maxLength: 64
          example: John
        lastName:
          type: string
          description: The last name of the recipient of this remittance.
          maxLength: 64
          example: Doe
    TransactionDetails:
      required:
        - transactionReference
        - originalAmount
        - originalCurrency
        - buyFxRate
        - senderFees
        - purposeOfFunds
        - sourceOfFunds
      type: object
      properties:
        transactionReference:
          type: string
          description: The unique reference to the transaction in your system
          maxLength: 64
          example: de83150a-5916-48a2-b048-bd85e022cb55
        originalAmount:
          type: string
          description: The original amount in the original currency that is being remitted.
          example: '100'
        originalCurrency:
          type: string
          maxLength: 3
          description: >
            The currency in which the remittance originates.

            Format must be the ISO 4217 three character currency code in upper
            case. Read more from
            [Wikipedia](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
          example: USD
        buyFxRate:
          type: string
          description: The fx rate applied to the customer for this remittance.
          example: '23.88'
        senderFees:
          type: string
          description: Any service and other fees paid by the customer for this remittance.
          example: '1'
        purposeOfFunds:
          type: string
          description: The intended purpose for the funds being remitted to the recipient.
          maxLength: 64
          enum:
            - FAMILY_SUPPORT
            - MEDICAL_EXPENSES
            - TUITION_FEES
            - EDUCATION_SUPPORT
            - GIFT_AND_OTHER_DONATIONS
            - HOME_IMPROVEMENT
            - DEBT_SETTLEMENT
            - REAL_ESTATE
            - TAXES
            - SALARY
            - SAVINGS
            - PERSONAL_TRANSFER
            - OTHER
          example: FAMILY_SUPPORT
        sourceOfFunds:
          type: string
          description: The source of the funds being remitted.
          maxLength: 64
          enum:
            - SALARY
            - SAVINGS
            - LOTTERY
            - LOAN
            - BUSINESS_INCOME
            - GIFT
            - OTHER
          example: SALARY
    SenderDetails:
      required:
        - firstName
        - lastName
        - nationality
        - phoneNumber
        - address
        - identification
      type: object
      properties:
        firstName:
          type: string
          description: The first name of the sender of this remittance.
          maxLength: 64
          example: Jane
        lastName:
          type: string
          description: The last name of the sender of this remittance.
          maxLength: 64
          example: Doe
        nationality:
          type: string
          minLength: 3
          maxLength: 3
          description: >
            The nationality of the sender of this remittance. Format is ISO
            3166-1 alpha-3, three character country code in upper case. Read
            more from
            [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
          example: USA
        gender:
          type: string
          description: The gender of the sender of this remittance.
          maxLength: 64
          enum:
            - MALE
            - FEMALE
            - OTHER
          example: FEMALE
        phoneNumber:
          type: string
          description: The phone number of the sender of this remittance.
          maxLength: 64
          example: '12124567890'
        dateOfBirth:
          type: string
          format: date
          description: The date of birth of the sender of this remittance.
          example: '1977-12-31'
        placeOfBirth:
          type: string
          description: The place of birth of the sender of this remittance.
          maxLength: 64
          example: USA
        occupation:
          type: string
          description: The occupation of the sender of this remittance.
          maxLength: 64
          example: Project manager
        relationshipRecipient:
          type: string
          description: >-
            The nature of the relationship between the sender and the recipient
            of this remittance.
          maxLength: 64
          enum:
            - FATHER
            - MOTHER
            - SON
            - DAUGHTER
            - BROTHER
            - SISTER
            - HUSBAND
            - WIFE
            - PARTNER
            - FRIEND
            - AUNT
            - UNCLE
            - COUSIN
            - NEPHEW
            - NIECE
            - GRANDFATHER
            - GRANDMOTHER
            - GRANDSON
            - GRANDDAUGHTER
            - STEPCHILD
            - DAUGHTER_IN_LAW
            - SON_IN_LAW
            - BORTHER_IN_LAW
            - SISTER_IN_LAW
            - MOTHER_IN_LAW
            - GUARDIAN
            - SELF
          example: PARTNER
        address:
          $ref: '#/components/schemas/SenderAddress'
        identification:
          $ref: '#/components/schemas/SenderIdentification'
    PhoneNumber:
      type: string
      description: >
        The phone number (MSISDN) of the customer paying or receiving payment.

        The format is described in
        [Wikipedia](https://en.wikipedia.org/wiki/MSISDN). 


        Use [predict provider](/v2/api-reference/toolkit/predict-provider) to
        validate and sanitise the phone number.


        Phone number validation has following rules:
         * Only digits without whitespaces or any other separators or prefixes like '+'.
         * Should not start with zero.
         * Country code is mandatory.
         * Should not exceed or be less than the valid length of specified country.
      example: '260763456789'
    RemittanceProvider:
      type: string
      description: >
        The provider represents the mobile money operator or processor that can
        process payments.


        Please contact our Sales team for a list of all the supported providers.


        The [active
        configuration](/v2/api-reference/toolkit/active-configuration) endpoint
        provides the list of provider configured for your account.


        You can use the [predict
        provider](/v2/api-reference/toolkit/predict-provider) enpoint to predict
        the provider to use based on the phone number (MSISDN).
      example: MTN_MOMO_ZMB
    SenderAddress:
      required:
        - addressLine
        - postalCode
        - city
        - country
      type: object
      properties:
        addressLine:
          type: string
          description: The address of the sender of this remittance.
          maxLength: 64
          example: 1476 Sandhill Rd
        postalCode:
          type: string
          description: The postal/zip code or the sender of this remittance.
          maxLength: 64
          example: '84058'
        city:
          type: string
          description: The city of the sender of this remittance.
          maxLength: 64
          example: Orem
        country:
          type: string
          minLength: 3
          maxLength: 3
          description: >
            The country of the sender of this remittance. Format is ISO 3166-1
            alpha-3, three character country code in upper case. Read more from
            [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements).
          example: USA
    SenderIdentification:
      required:
        - type
        - number
      type: object
      properties:
        type:
          type: string
          description: >-
            The type of identification document used to KYC the sender of this
            remittance.
          example: PASSPORT
          enum:
            - NATIONAL_ID
            - PASSPORT
            - DRIVING_LICENSE
            - SOCIAL_SECURITY_ID
            - RESIDENCE_PERMIT
        number:
          type: string
          description: >-
            The id of the identification document used to KYC the sender of this
            remittance.
          maxLength: 64
          example: E00007730
  securitySchemes:
    bearerAuth:
      type: http
      description: >-
        See
        [Authentication](/v2/docs/how_to_start#how-to-authenticate-calls-to-the-merchant-api).
      scheme: bearer
      bearerFormat: JWT

````